@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

npm install @factordao/governance
# or
yarn add @factordao/governance

Supported Chains

• Arbitrum One
• Base
• Optimism
• Sonic

Quick Start

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.

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.

import { getVaultsWithFullData, FactorEnvironment } from "@factordao/governance";

const vaults = await getVaultsWithFullData(FactorEnvironment.PRODUCTION);
// Returns: AggregatedVault[]

Returns:

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.

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.

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.

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.

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.

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:

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).

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.

import { getTokenBalancesForAllUsers, FactorEnvironment } from "@factordao/governance";
import { ChainId } from "@factordao/tokenlist";

const allBalances = await getTokenBalancesForAllUsers(
  ChainId.ARBITRUM_ONE,
  FactorEnvironment.PRODUCTION
);
// Returns: AllUsersTokenBalances

Types

Enums

enum FactorEnvironment {
  TESTING = "testing",
  STAGING = "staging",
  PRODUCTION = "production",
}

Core Types

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:

ALCHEMY_API_KEY=<your-alchemy-api-key>  # Optional, improves RPC reliability
FACTOR_ENVIRONMENT=production            # testing | staging | production

Using with Environment Variable

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

git clone <repo>
cd factor-governance
yarn install

Scripts

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

# 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