@glowlabs-org/utils 0.2.155 → 0.2.157

package/README.md

@@ -72,19 +72,18 @@ See `src/lib/hooks/use-forwarder.ts` for all available helpers (`approveToken`,
 
 ### Control-API SDK (framework-agnostic)
 
+The Control API provides a comprehensive set of routers for interacting with the Glow protocol. All methods are promise-based and framework-agnostic – usable in Node, Deno, or the browser.
+
+#### Quick Start
+
 ```typescript
 import { ControlRouter } from "@glowlabs-org/utils";
 
-// Base URL of your deployed Control-API instance (can be relative or absolute)
 const controlApi = ControlRouter("https://control-api.glowlabs.org");
 
 // Read-only queries
 const balance = await controlApi.fetchGctlBalance("0xYourWallet");
 const price = await controlApi.fetchGctlPrice();
-const glwPrice = await controlApi.fetchGlwPrice();
-
-// Paginated listings
-const mintedPage2 = await controlApi.fetchMintedEvents(2, 25);
 
 // Mutations
 await controlApi.stakeGctl({
@@ -97,26 +96,185 @@ await controlApi.stakeGctl({
 });
 ```
 
-All methods are promise-based and contain zero React dependencies – usable in Node, Deno or the browser.
+---
+
+#### ControlRouter
+
+Main router for GCTL token operations, balances, and staking.
+
+**Queries:**
+
+- `fetchGctlBalance(wallet)` → `string` - Get GCTL balance for a wallet
+- `fetchCommittedBalance(wallet)` → `string` - Get committed GCTL balance
+- `fetchGctlPrice()` → `string` - Current GCTL price in USDC
+- `fetchGlwPrice()` → `string` - Current GLW price in USDC
+- `fetchCirculatingSupply()` → `string` - Circulating supply of GCTL
+- `fetchHoldersCount()` → `number` - Total number of GCTL holders
+- `fetchLastNonce(wallet)` → `string` - Last nonce for wallet (type: `WalletNonce`)
+- `fetchMintedEvents(page?, limit?)` → `MintedEventsResponse` - Paginated minted events
+- `fetchStakeEvents(page?, limit?, regionId?)` → `StakeEventsResponse` - Paginated stake events
+- `fetchPendingTransfers(page?, limit?, type?)` → `PendingTransfersResponse` - Pending transfers with optional type filter
+- `fetchTransferDetails(txId)` → `TransferDetails` - Details for a specific transfer
+- `fetchFailedOperations(page?, limit?)` → `FailedOperationsResponse` - Failed operations
+- `fetchRegionStake(regionId)` → `RegionStake` - Total stake for a region
+- `fetchWalletRegionStake(wallet, regionId)` → `WalletRegionStake` - Wallet's stake in a region
+- `fetchWalletRegionUnlocked(wallet, regionId)` → `WalletRegionUnlocked` - Unlocked amount for wallet in region
+- `fetchWalletRegionCommittedBalance(wallet, regionId)` → `WalletRegionCommittedBalance` - Committed balance
+- `fetchGlwRegionRewards()` → `GlwRegionRewardsResponse` - GLW rewards by region
+- `fetchFarmRewardSplits(farmId)` → `FarmRewardSplit[]` - Reward splits for a farm
+- `fetchMigrationAmount(wallet)` → `MigrationAmountResponse` - Migration amount for wallet
+
+**Mutations:**
+
+- `stakeGctl(request)` - Stake GCTL to a region (type: `StakeRequest`)
+- `unstakeGctl(request)` - Unstake GCTL from a region (type: `StakeRequest`)
+- `restakeGctl(request)` - Move stake between regions (type: `RestakeRequest`)
+- `retryFailedOperation(operationId)` → `RetryFailedOperationResponse` - Retry a failed operation
+- `payProtocolDepositUsingStakedControl(request)` → `PayProtocolDepositUsingStakedControlResponse` - Pay protocol deposit using staked GCTL
+- `migrateUser(request)` → `MigrateUserResponse` - Migrate user from v1 to v2
+
+**Processing Flags:**
+
+- `isStaking`, `isUnstaking`, `isRestaking`, `isRetryingFailedOperation`, `isPayingProtocolDepositUsingStakedControl`, `isMigratingUser`
 
 ---
 
-### Region-API SDK (framework-agnostic)
+#### WalletsRouter
 
-```typescript
-import { RegionRouter } from "@glowlabs-org/utils";
+Router for wallet-specific data including balances, farms, and rewards.
 
-const regionsApi = RegionRouter("https://control-api.glowlabs.org");
+**Queries:**
 
-// Fetch & cache
-await regionsApi.fetchRegions();
-console.table(regionsApi.regions);
+- `fetchAllWallets()` → `ControlWallet[]` - All wallets with balances
+- `fetchWalletByAddress(wallet)` → `WalletDetails` - Wallet details including regions and farms
+- `fetchWalletMintedEvents(wallet, page?, limit?)` → `MintedEvent[]` - Minted events for wallet
+- `fetchWalletStakeEvents(wallet, page?, limit?, regionId?)` → `StakedEvent[]` - Stake events for wallet
+- `fetchWalletWeeklyRewards(wallet, query?)` → `WalletWeeklyRewardsResponse` - Weekly rewards aggregated by payment currency (query: `WeeklyRewardsQuery` with `startWeek`, `endWeek`, `paymentCurrency`, `limit`)
 
-// Convenience helper merges bundled metadata with fetched regions
-const maybeFlorida = regionsApi.getRegionByCode("US-FL");
-```
+**Key Types:**
+
+- `WalletDetails` - Includes `controlBalance`, `stakedControl`, `committedControl`, `regions` (array of `WalletRegionStakeTotal`), and `ownedFarms` (array of `WalletFarmInfo` with reward splits)
+- `WalletWeeklyRewardsResponse` - Contains `summary` (`WeeklyRewardsSummary`) and `rewards` (array of `WeeklyReward`)
+
+---
+
+#### RegionRouter
+
+Router for geographic regions, activation, and regional data.
+
+**Queries:**
+
+- `fetchRegions(params?)` → `RegionWithMetadata[]` - All regions, optionally filtered by `isActive`
+- `fetchRegionByIdOrSlug(idOrSlug)` → `RegionDetails` - Detailed region info including farms and applications
+- `fetchActivationConfig(regionCode)` → `ActivationConfig` - Activation thresholds and requirements
+- `fetchActivationEvents(regionId?)` → `ActivationEvent[]` - Activation event timeline
+- `fetchRegionSolarFarms(regionId)` → `SponsoredFarm[]` - Solar farms in a region
+- `fetchActiveSummary()` → `ActiveRegionsSummaryResponse` - Chart-ready data with 4-epoch history
+- `fetchRecentActivity()` → `RecentRegionActivityResponse` - 24h and 7d activity statistics
+- `fetchRegionWeeklyRewards(regionId, query?)` → `RegionWeeklyRewardsResponse` - Weekly rewards aggregated by payment currency (query: `RegionWeeklyRewardsQuery`)
+- `getRegionByCode(code)` → `RegionWithMetadata | null` - Get region by code, merges bundled metadata
+
+**Mutations:**
+
+- `applyInstallerCertification(payload)` → `InstallerApplicationResponse` - Apply for installer certification (type: `InstallerApplicationPayload`)
+
+**Cached Data:**
+
+- `regions` - Cached regions array
+- `isLoading` - Loading state flag
+
+**Key Types:**
+
+- `RegionWithMetadata` - Includes activation progress (stake, farms, installers)
+- `RegionDetails` - Full region view with farms, applications, and carbon credits
+- `ActiveRegionsSummaryResponse` - Historical data with metadata, totals, per-region data, and aggregate timeline
+- `RegionWeeklyRewardsResponse` - Summary and rewards array by week and payment currency
+
+---
+
+#### FarmsRouter
+
+Router for solar farm operations, rewards, and scoring.
+
+**Queries:**
 
-`getRegionByCode()` merges locally-bundled metadata (flag, description, etc.) from `src/lib/region-metadata.ts`.
+- `fetchFarmRewardSplits(farmId)` → `FarmRewardSplit[]` - Current reward splits for a farm
+- `fetchSponsoredFarms(sponsorWallet?)` → `SponsoredFarm[]` - All sponsored farms, optionally filtered by sponsor
+- `fetchWalletFarmsWithRewards(walletAddress)` → `FarmWithRewards[]` - Farms where wallet has reward splits, with calculated weekly rewards
+- `fetchFarmWeeklyRewards(farmId, query?)` → `FarmWeeklyRewardsResponse` - Weekly rewards aggregated by payment currency (query: `FarmWeeklyRewardsQuery`)
+
+**Mutations:**
+
+- `estimateRewardScore(params)` → `RewardScoreResponse` - Calculate reward score for a potential farm (type: `EstimateRewardScoreParams`)
+- `estimateRewardScoresBatch(params)` → `EstimateRewardScoresBatchResponse` - Calculate reward scores for multiple farms (type: `EstimateRewardScoresBatchParams`)
+- `calculateMiningScoresBatch(params)` → `MiningScoresBatchResponse` - Calculate mining scores for existing farms (type: `MiningScoresBatchParams`)
+
+**Key Types:**
+
+- `SponsoredFarm` - Complete farm details including location, capacity, pictures, and reward splits
+- `FarmWithRewards` - Extends `SponsoredFarm` with `userWeeklyRewards` (`UserWeeklyRewards`)
+- `RewardScoreResponse` - Comprehensive reward estimates including weekly PD/GLW rewards, USD values, and region info
+- `MiningScoreResponse` - Mining ROI calculation with GLW rewards and lifetime estimates
+- `FarmWeeklyRewardsResponse` - Summary and rewards array by week and payment currency
+
+---
+
+#### KickstarterRouter
+
+Router for region kickstarter campaigns and commitments.
+
+**Queries:**
+
+- `fetchKickstarters()` → `Kickstarter[]` - All kickstarters
+- `fetchKickstarter(idOrSlug)` → `KickstarterDetails` - Detailed kickstarter info including contributors and farms
+- `fetchKickstartersByWallet(wallet)` → `Kickstarter[]` - Kickstarters by creator wallet
+- `fetchRegionCommitments(regionId, query?)` → `KickstarterCommitmentsResponse` - Paginated commitments (query: `KickstarterCommitmentsQuery` with `page`, `limit`, `finalized`)
+
+**Mutations:**
+
+- `createKickstarter(payload)` → `KickstarterCreateResponse` - Create a new kickstarter (type: `CreateKickstarterPayload`)
+- `commitKickstarter(kickstarterId, payload)` → `CommitKickstarterResponse` - Commit GCTL to a kickstarter (type: `CommitKickstarterPayload`)
+
+**Processing Flags:**
+
+- `isCreatingKickstarter`
+
+**Key Types:**
+
+- `Kickstarter` - Basic kickstarter info with status, targets, and progress flags
+- `KickstarterDetails` - Extends `Kickstarter` with contributors, farm count, applications, and sponsored farms
+- `KickstarterStatus` - Status enum: `draft`, `collecting-support`, `completed`, `failed`, `cancelled`
+
+---
+
+### Using Individual Routers
+
+Each router can be imported and used independently:
+
+```typescript
+import {
+  ControlRouter,
+  WalletsRouter,
+  RegionRouter,
+  FarmsRouter,
+  KickstarterRouter,
+} from "@glowlabs-org/utils";
+
+const baseUrl = "https://control-api.glowlabs.org";
+
+const control = ControlRouter(baseUrl);
+const wallets = WalletsRouter(baseUrl);
+const regions = RegionRouter(baseUrl);
+const farms = FarmsRouter(baseUrl);
+const kickstarters = KickstarterRouter(baseUrl);
+
+// Use any router
+const balance = await control.fetchGctlBalance("0x...");
+const walletDetails = await wallets.fetchWalletByAddress("0x...");
+const regionList = await regions.fetchRegions({ isActive: true });
+const farmSplits = await farms.fetchFarmRewardSplits("farm-id");
+const allKickstarters = await kickstarters.fetchKickstarters();
+```
 
 ---
 

package/dist/cjs/browser.d.ts

@@ -1,5 +1,6 @@
 export * from "./lib/hooks/use-forwarder";
 export * from "./lib/hooks/use-offchain-fractions";
+export * from "./lib/hooks/use-rewards-kernel";
 export * from "./lib/control-api/control-router";
 export * from "./lib/control-api/region-router";
 export * from "./lib/control-api/kickstarter-router";
@@ -9,6 +10,7 @@ export * from "./lib/types";
 export * from "./lib/region-metadata";
 export * from "./lib/abis/forwarderABI";
 export * from "./lib/abis/offchainFractions";
+export * from "./lib/abis/rewardKernelABI";
 export * from "./constants/addresses";
 export * from "./constants/weights";
 export * from "./constants/urls";

package/dist/cjs/browser.js

@@ -1,6 +1,6 @@
 'use strict';
 
-var farmsRouter = require('./farms-router-BOXNLl3m.js');
+var farmsRouter = require('./farms-router-DekpTBQj.js');
 var viem = require('viem');
 require('ethers');
 
@@ -12438,7 +12438,12 @@ Object.defineProperty(exports, "REGIONS", {
     enumerable: true,
     get: function () { return farmsRouter.REGIONS; }
 });
+exports.REWARDS_KERNEL_ABI = farmsRouter.REWARDS_KERNEL_ABI;
 exports.RegionRouter = farmsRouter.RegionRouter;
+Object.defineProperty(exports, "RewardsKernelError", {
+    enumerable: true,
+    get: function () { return farmsRouter.RewardsKernelError; }
+});
 Object.defineProperty(exports, "STAKING_DIRECTIONS", {
     enumerable: true,
     get: function () { return farmsRouter.STAKING_DIRECTIONS; }
@@ -12456,6 +12461,7 @@ exports.regionMetadata = farmsRouter.regionMetadata;
 exports.usStates = farmsRouter.usStates;
 exports.useForwarder = farmsRouter.useForwarder;
 exports.useOffchainFractions = farmsRouter.useOffchainFractions;
+exports.useRewardsKernel = farmsRouter.useRewardsKernel;
 exports.waitForEthersTransactionWithRetry = farmsRouter.waitForEthersTransactionWithRetry;
 exports.waitForViemTransactionWithRetry = farmsRouter.waitForViemTransactionWithRetry;
 exports.applyCertifiedInstallerEIP712Types = applyCertifiedInstallerEIP712Types;