@factordao/governance 1.1.3 → 1.1.4

package/README.md

@@ -1,18 +1,362 @@
-# Factor Governance
-
-This repository contains the governance for Factor.
-
-## Implementation plan
-- [x] Create the subgraph to track the `emit AddVault(_chainId, _vault);` event from `FactorScale` on Arbitrum
-- [x] Create the function to get all the vaults for all the available chains
-- [x] Create the subgraph to track the `emit Vote(user, vaults[i], weights[i], newVote);` event from `FactorScale`
-- [x] Create the function to get all the votes for a given user
-- [x] Create the function to get all the votes for all the users
-- [x] Create the function to get all the votes allocations
-- [x] Create the subgraph to track the `emit ReceiveVotingResults(wTime, vaults, fctrAmounts);` event from `FactorGaugeController` of both Arbitrum and Base which is emitted after the broadcast
-- [x] Create the subgraph to track the `emit UpdateVaultReward(vault, newSpeed, uint128(block.timestamp) + WEEK);` event from `FactorGaugeController`
-- [x] Create the function to get all the rewards for a given vault
-- [x] Create the function to get all the rewards for all vaults
-- [x] Create the function to get the incentives, if they're active or not and how much they're worth
-- [x] Calculate the APY for scale and the given vault (?)
-- [ ] Create the function to get the `function earned(address account, address _rewardsToken)` for a given account and rewards token to get the rewards for the user (?)
+# @factordao/governance
+
+A TypeScript SDK for Factor DAO's governance system. Provides data fetching for vaults, voting, rewards, and token balances across multiple blockchain networks.
+
+## Installation
+
+```bash
+npm install @factordao/governance
+# or
+yarn add @factordao/governance
+```
+
+## Supported Chains
+
+- Arbitrum One
+- Base
+- Optimism
+- Sonic
+
+## Quick Start
+
+```typescript
+import {
+  getVaultsWithFullData,
+  getVaultsRewardsData,
+  FactorEnvironment,
+} from "@factordao/governance";
+
+// Get all vaults with aggregated data (votes, rewards, APY)
+const vaults = await getVaultsWithFullData(FactorEnvironment.PRODUCTION);
+
+// Get detailed reward data for specific vaults
+const rewardsData = await getVaultsRewardsData(
+  [{ address: "0x...", chainId: 42161 }],
+  "0xUserAddress", // optional
+  "your-alchemy-key" // optional
+);
+```
+
+## API Reference
+
+### Vault Functions
+
+#### `getAvailableVaultsForVoting(chainId, environment)`
+
+Fetches all available vaults for voting on a specific chain.
+
+```typescript
+import { getAvailableVaultsForVoting, FactorEnvironment } from "@factordao/governance";
+import { ChainId } from "@factordao/tokenlist";
+
+const vaults = await getAvailableVaultsForVoting(
+  ChainId.ARBITRUM_ONE,
+  FactorEnvironment.PRODUCTION
+);
+// Returns: string[] - Array of vault addresses
+```
+
+#### `getVaultsWithFullData(environment)`
+
+Comprehensive function that aggregates vault data, votes, voting power, and rewards across all chains with calculated APY.
+
+```typescript
+import { getVaultsWithFullData, FactorEnvironment } from "@factordao/governance";
+
+const vaults = await getVaultsWithFullData(FactorEnvironment.PRODUCTION);
+// Returns: AggregatedVault[]
+```
+
+**Returns:**
+```typescript
+interface AggregatedVault {
+  id: string;                           // Vault address
+  chainId: number;                      // Chain ID
+  votes: VaultVoteAllocation[];         // Vote allocations
+  totalAllocatedVeFCTR: bigint;         // Total veFCTR allocated
+  voteSharePercentage: number;          // Percentage of total votes
+  rewards: VaultRewardByChain[];        // Reward data by chain
+}
+```
+
+### Voting Functions
+
+#### `getVotesForUser(chainId, environment, user)`
+
+Gets voting data for a specific user.
+
+```typescript
+import { getVotesForUser, FactorEnvironment } from "@factordao/governance";
+import { ChainId } from "@factordao/tokenlist";
+
+const votes = await getVotesForUser(
+  ChainId.ARBITRUM_ONE,
+  FactorEnvironment.PRODUCTION,
+  "0xUserAddress"
+);
+// Returns: VaultVotes[]
+```
+
+#### `getVotesForAllUsers(chainId, environment)`
+
+Fetches all votes across all users.
+
+```typescript
+import { getVotesForAllUsers, FactorEnvironment } from "@factordao/governance";
+import { ChainId } from "@factordao/tokenlist";
+
+const allVotes = await getVotesForAllUsers(
+  ChainId.ARBITRUM_ONE,
+  FactorEnvironment.PRODUCTION
+);
+// Returns: VaultVotes[]
+```
+
+### Reward Functions
+
+#### `getRewardsForVault(chainId, environment, vault)`
+
+Gets reward data for a specific vault.
+
+```typescript
+import { getRewardsForVault, FactorEnvironment } from "@factordao/governance";
+import { ChainId } from "@factordao/tokenlist";
+
+const rewards = await getRewardsForVault(
+  ChainId.ARBITRUM_ONE,
+  FactorEnvironment.PRODUCTION,
+  "0xVaultAddress"
+);
+// Returns: VaultReward[]
+```
+
+#### `getRewardsForAllVaults(chainId, environment)`
+
+Fetches rewards for all vaults on a chain.
+
+```typescript
+import { getRewardsForAllVaults, FactorEnvironment } from "@factordao/governance";
+import { ChainId } from "@factordao/tokenlist";
+
+const allRewards = await getRewardsForAllVaults(
+  ChainId.ARBITRUM_ONE,
+  FactorEnvironment.PRODUCTION
+);
+// Returns: VaultReward[]
+```
+
+#### `getVaultsRewardsData(vaults, userAddress?, alchemyApiKey?)`
+
+Fetches detailed Scale/Boost reward data using multicalls. This is the most comprehensive reward function.
+
+```typescript
+import { getVaultsRewardsData } from "@factordao/governance";
+
+const rewardsData = await getVaultsRewardsData(
+  [
+    { address: "0xVault1", chainId: 42161 },
+    { address: "0xVault2", chainId: 8453 },
+  ],
+  "0xUserAddress", // optional - include for user-specific pending rewards
+  "your-alchemy-key" // optional - improves RPC reliability
+);
+// Returns: VaultRewardsData[]
+```
+
+**Returns:**
+```typescript
+interface VaultRewardsData {
+  vaultAddress: string;
+  chainId: number;
+  scale: {
+    rewardTokens: RewardTokenInfo[];
+    totalActiveSupply: bigint;
+    rewardsData: Record<string, RewardData>;
+  };
+  boost: {
+    rewardTokens: RewardTokenInfo[];
+    rewardsData: Record<string, RewardData>;
+  };
+  user?: {
+    activeBalance: bigint;
+    scalePendingByToken: Record<string, bigint>;
+    earnedByToken: Record<string, bigint>;
+  };
+}
+```
+
+### Token Balance Functions
+
+#### `getTokenBalancesForUser(chainId, environment, user)`
+
+Gets token balances for a specific user (veFCTR with voting power).
+
+```typescript
+import { getTokenBalancesForUser, FactorEnvironment } from "@factordao/governance";
+import { ChainId } from "@factordao/tokenlist";
+
+const balances = await getTokenBalancesForUser(
+  ChainId.ARBITRUM_ONE,
+  FactorEnvironment.PRODUCTION,
+  "0xUserAddress"
+);
+// Returns: UserTokenBalances
+```
+
+#### `getTokenBalancesForAllUsers(chainId, environment)`
+
+Fetches all user token balances.
+
+```typescript
+import { getTokenBalancesForAllUsers, FactorEnvironment } from "@factordao/governance";
+import { ChainId } from "@factordao/tokenlist";
+
+const allBalances = await getTokenBalancesForAllUsers(
+  ChainId.ARBITRUM_ONE,
+  FactorEnvironment.PRODUCTION
+);
+// Returns: AllUsersTokenBalances
+```
+
+## Types
+
+### Enums
+
+```typescript
+enum FactorEnvironment {
+  TESTING = "testing",
+  STAGING = "staging",
+  PRODUCTION = "production",
+}
+```
+
+### Core Types
+
+```typescript
+interface VaultVotes {
+  id: string;
+  user: string;
+  vault: string;
+  weight: bigint;
+  newVote: boolean;
+}
+
+interface VoteData {
+  weight: bigint;
+  newVote: boolean;
+}
+
+interface VaultReward {
+  id: string;
+  vault: string;
+  speed: bigint;
+  activeFrom: bigint;
+}
+
+interface TokenBalance {
+  id: string;
+  amount: bigint;
+  expiry: bigint;
+}
+
+interface UserTokenBalances {
+  balances: TokenBalance[];
+  votingPower: bigint;
+}
+
+interface AllUsersTokenBalances {
+  [userAddress: string]: UserTokenBalances;
+}
+
+interface VaultVoteAllocation {
+  user: string;
+  weight: bigint;
+  votingPower: bigint;
+}
+
+interface VaultRewardByChain {
+  chainId: number;
+  speed: bigint;
+  activeFrom: bigint;
+}
+
+interface RewardTokenInfo {
+  token: string;
+  symbol: string;
+  decimals: number;
+}
+
+interface RewardData {
+  rewardPerSecond: bigint;
+  periodFinish: bigint;
+  apr: number;
+}
+```
+
+## Configuration
+
+### Environment Variables
+
+Create a `.env` file:
+
+```env
+ALCHEMY_API_KEY=<your-alchemy-api-key>  # Optional, improves RPC reliability
+FACTOR_ENVIRONMENT=production            # testing | staging | production
+```
+
+### Using with Environment Variable
+
+```typescript
+import { getVaultsWithFullData, FactorEnvironment } from "@factordao/governance";
+
+const environment =
+  (process.env.FACTOR_ENVIRONMENT as FactorEnvironment) ||
+  FactorEnvironment.PRODUCTION;
+
+const vaults = await getVaultsWithFullData(environment);
+```
+
+## Data Sources
+
+The SDK fetches data from:
+
+- **Subgraphs (Goldsky)** - Vault, voting, and reward event data
+- **Factor Price API** - FCTR token prices
+- **Factor Studio Stats API** - Vault TVL data
+- **DefiLlama** - Token prices for reward calculations
+- **RPC Providers** - On-chain contract reads via multicall
+
+## Development
+
+### Setup
+
+```bash
+git clone <repo>
+cd factor-governance
+yarn install
+```
+
+### Scripts
+
+```bash
+yarn build     # Build ESM and CJS outputs
+yarn dev       # Run with ts-node
+yarn lint      # Fix linting issues
+yarn format    # Format code with Prettier
+```
+
+### Running Tests
+
+```bash
+# Create .env file first
+cp .env.example .env
+
+# Run test scripts
+npx ts-node test/01-get-vaults-with-full-data.ts
+npx ts-node test/02-get-vaults-rewards-data.ts
+npx ts-node test/03-performance-test.ts
+```
+
+## License
+
+MIT

package/dist/cjs/utils/subgraphs.js

@@ -33,7 +33,7 @@ async function fetchPaginatedData(subgraphUrl, queryBuilder, dataExtractor) {
 }
 exports.factorScaleSubgraphUrl = {
     [tokenlist_1.ChainId.ARBITRUM_ONE]: {
-        testing: 'https://api.goldsky.com/api/public/project_cmgzitcts001c5np28moc9lyy/subgraphs/scale-arbitrum_testing/v0.0.4/gn',
+        testing: 'https://api.goldsky.com/api/public/project_cmgzitcts001c5np28moc9lyy/subgraphs/scale-arbitrum_testing/v0.0.5/gn',
         production: 'https://api.goldsky.com/api/public/project_cmgzitcts001c5np28moc9lyy/subgraphs/scale-arbitrum_production/v0.0.4/gn',
     },
     [tokenlist_1.ChainId.BASE]: {
@@ -51,11 +51,11 @@ exports.factorScaleSubgraphUrl = {
 };
 exports.factorGaugeControllerSubgraphUrl = {
     [tokenlist_1.ChainId.ARBITRUM_ONE]: {
-        testing: 'https://api.goldsky.com/api/public/project_cmgzitcts001c5np28moc9lyy/subgraphs/gauge-arbitrum_testing/v0.0.2/gn',
+        testing: 'https://api.goldsky.com/api/public/project_cmgzitcts001c5np28moc9lyy/subgraphs/gauge-arbitrum_testing/v0.0.3/gn',
         production: 'https://api.goldsky.com/api/public/project_cmgzitcts001c5np28moc9lyy/subgraphs/gauge-arbitrum_production/v0.0.2/gn',
     },
     [tokenlist_1.ChainId.BASE]: {
-        testing: 'https://api.goldsky.com/api/public/project_cmgzitcts001c5np28moc9lyy/subgraphs/gauge-base_testing/v0.0.2/gn',
+        testing: 'https://api.goldsky.com/api/public/project_cmgzitcts001c5np28moc9lyy/subgraphs/gauge-base_testing/v0.0.3/gn',
         production: '',
     },
     [tokenlist_1.ChainId.OPTIMISM]: {
@@ -69,7 +69,7 @@ exports.factorGaugeControllerSubgraphUrl = {
 };
 exports.factorFCTRSubgraphUrl = {
     [tokenlist_1.ChainId.ARBITRUM_ONE]: {
-        testing: 'https://api.goldsky.com/api/public/project_cmgzitcts001c5np28moc9lyy/subgraphs/token-balance-arbitrum_testing/v0.0.4/gn',
+        testing: 'https://api.goldsky.com/api/public/project_cmgzitcts001c5np28moc9lyy/subgraphs/token-balance-arbitrum_testing/v0.0.5/gn',
         production: 'https://api.goldsky.com/api/public/project_cmgzitcts001c5np28moc9lyy/subgraphs/token-balance-arbitrum_production/v0.0.2/gn',
     },
     [tokenlist_1.ChainId.BASE]: {

package/dist/mjs/utils/subgraphs.js

@@ -29,7 +29,7 @@ export async function fetchPaginatedData(subgraphUrl, queryBuilder, dataExtracto
 }
 export const factorScaleSubgraphUrl = {
     [ChainId.ARBITRUM_ONE]: {
-        testing: 'https://api.goldsky.com/api/public/project_cmgzitcts001c5np28moc9lyy/subgraphs/scale-arbitrum_testing/v0.0.4/gn',
+        testing: 'https://api.goldsky.com/api/public/project_cmgzitcts001c5np28moc9lyy/subgraphs/scale-arbitrum_testing/v0.0.5/gn',
         production: 'https://api.goldsky.com/api/public/project_cmgzitcts001c5np28moc9lyy/subgraphs/scale-arbitrum_production/v0.0.4/gn',
     },
     [ChainId.BASE]: {
@@ -47,11 +47,11 @@ export const factorScaleSubgraphUrl = {
 };
 export const factorGaugeControllerSubgraphUrl = {
     [ChainId.ARBITRUM_ONE]: {
-        testing: 'https://api.goldsky.com/api/public/project_cmgzitcts001c5np28moc9lyy/subgraphs/gauge-arbitrum_testing/v0.0.2/gn',
+        testing: 'https://api.goldsky.com/api/public/project_cmgzitcts001c5np28moc9lyy/subgraphs/gauge-arbitrum_testing/v0.0.3/gn',
         production: 'https://api.goldsky.com/api/public/project_cmgzitcts001c5np28moc9lyy/subgraphs/gauge-arbitrum_production/v0.0.2/gn',
     },
     [ChainId.BASE]: {
-        testing: 'https://api.goldsky.com/api/public/project_cmgzitcts001c5np28moc9lyy/subgraphs/gauge-base_testing/v0.0.2/gn',
+        testing: 'https://api.goldsky.com/api/public/project_cmgzitcts001c5np28moc9lyy/subgraphs/gauge-base_testing/v0.0.3/gn',
         production: '',
     },
     [ChainId.OPTIMISM]: {
@@ -65,7 +65,7 @@ export const factorGaugeControllerSubgraphUrl = {
 };
 export const factorFCTRSubgraphUrl = {
     [ChainId.ARBITRUM_ONE]: {
-        testing: 'https://api.goldsky.com/api/public/project_cmgzitcts001c5np28moc9lyy/subgraphs/token-balance-arbitrum_testing/v0.0.4/gn',
+        testing: 'https://api.goldsky.com/api/public/project_cmgzitcts001c5np28moc9lyy/subgraphs/token-balance-arbitrum_testing/v0.0.5/gn',
         production: 'https://api.goldsky.com/api/public/project_cmgzitcts001c5np28moc9lyy/subgraphs/token-balance-arbitrum_production/v0.0.2/gn',
     },
     [ChainId.BASE]: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@factordao/governance",
-  "version": "1.1.3",
+  "version": "1.1.4",
   "license": "MIT",
   "files": [
     "dist",