@net-protocol/score 0.1.3 → 0.1.5

package/dist/index.d.mts

@@ -1,6 +1,6 @@
-import { S as ScoreClientOptions, G as GetUpvotesOptions, a as GetUpvotesForItemsOptions, b as GetStrategyKeyScoresOptions, c as GetAppKeyScoresOptions, D as DecodedStrategyMetadata, P as PoolKey, d as PoolDiscoveryResult } from './scoreKeyUtils-DgHOtf44.mjs';
-export { e as DecodedUpvoteBlob, F as FeedMessage, f as PoolStrategyMetadata, g as PureAlphaMetadata, h as ScoreItem, U as UseTokenUpvotesOptions, i as UseUpvotesBatchOptions, j as UseUpvotesOptions, k as extractTokenAddressFromScoreKey, l as getFeedContentKey, m as getScoreKey, n as getStorageScoreKey, o as getStorageUpvoteContext, p as getTokenScoreKey, q as isTokenScoreKey } from './scoreKeyUtils-DgHOtf44.mjs';
-import { Address, PublicClient, Abi } from 'viem';
+import { S as ScoreClientOptions, G as GetUpvotesOptions, a as GetUpvotesForItemsOptions, b as GetStrategyKeyScoresOptions, c as GetAppKeyScoresOptions, D as DecodedStrategyMetadata, P as PoolKey, d as PoolDiscoveryResult } from './scoreKeyUtils-DuH70ypB.mjs';
+export { e as DecodedUpvoteBlob, F as FeedMessage, f as PoolStrategyMetadata, g as PureAlphaMetadata, h as ScoreItem, U as UseTokenUpvotesOptions, i as UseUpvotePriceOptions, j as UseUpvoteUserOptions, k as UseUpvotesBatchOptions, l as UseUpvotesOptions, m as UseUserUpvotesGivenOptions, n as UseUserUpvotesGivenPerTokenBatchOptions, o as UseUserUpvotesReceivedOptions, p as UseUserUpvotesReceivedPerTokenBatchOptions, q as extractTokenAddressFromScoreKey, r as getFeedContentKey, s as getScoreKey, t as getStorageScoreKey, u as getStorageUpvoteContext, v as getTokenScoreKey, w as isTokenScoreKey } from './scoreKeyUtils-DuH70ypB.mjs';
+import { Address, WalletClient, PublicClient, Abi } from 'viem';
 
 /**
  * ScoreClient - Client for interacting with Net protocol scoring/upvote system
@@ -37,6 +37,118 @@ declare class ScoreClient {
     getAppKeyScores({ app, scoreKeys, }: GetAppKeyScoresOptions): Promise<number[]>;
 }
 
+type ParsedUserUpvoteMessage = {
+    upvotedUserString: string;
+    actualToken: string;
+    numUpvotes: number;
+    tokenWethPrice: bigint;
+    wethUsdcPrice: bigint;
+    alphaWethPrice: bigint;
+    userTokenBalance?: bigint;
+};
+type TokenAddressExtraction = {
+    tokenAddresses: string[];
+    validMessages: ParsedUserUpvoteMessage[];
+};
+type UserUpvote = {
+    tokenAddress: string;
+    numUpvotes: number;
+    timestamp: number;
+    priceInUsdc?: number;
+    userTokenBalance: number;
+    userTokenBalanceUsdValue?: number;
+    upvotedUserAddress?: string;
+    tokenInfo?: {
+        name: string;
+        symbol: string;
+        decimals: number;
+    };
+};
+type UserUpvoteReceived = {
+    upvoterAddress: string;
+    tokenAddress: string;
+    numUpvotes: number;
+    timestamp: number;
+    priceInUsdc?: number;
+    userTokenBalance: number;
+    userTokenBalanceUsdValue?: number;
+    tokenInfo?: {
+        name: string;
+        symbol: string;
+        decimals: number;
+    };
+};
+type UserUpvoteClientOptions = {
+    chainId: number;
+    overrides?: {
+        contractAddress?: Address;
+        rpcUrls?: string[];
+    };
+};
+type UserUpvoteNetMessage = {
+    app: `0x${string}`;
+    sender: `0x${string}`;
+    timestamp: bigint;
+    data: `0x${string}`;
+    text: string;
+    topic: string;
+};
+
+/**
+ * UserUpvoteClient - Client for reading user-to-user upvote data.
+ *
+ * This is a standalone upvote system separate from the token Score system.
+ * It reads directly from the UserUpvote contract on Base.
+ */
+declare class UserUpvoteClient {
+    private client;
+    private contractAddress;
+    private chainId;
+    constructor(params: UserUpvoteClientOptions);
+    getUserUpvotesGiven({ user }: {
+        user: Address;
+    }): Promise<bigint>;
+    getUserUpvotesReceived({ user }: {
+        user: Address;
+    }): Promise<bigint>;
+    getUserUpvotesGivenPerTokenBatch({ user, tokens, }: {
+        user: Address;
+        tokens: Address[];
+    }): Promise<bigint[]>;
+    getUserUpvotesReceivedPerTokenBatch({ user, tokens, }: {
+        user: Address;
+        tokens: Address[];
+    }): Promise<bigint[]>;
+    getTotalUpvotesPerToken({ token, }: {
+        token: Address;
+    }): Promise<bigint>;
+    getUserTokensInRange({ user, startIndex, endIndex, }: {
+        user: Address;
+        startIndex: number;
+        endIndex: number;
+    }): Promise<{
+        token: Address;
+        feeTier: number;
+    }[]>;
+    getUserTokenCount({ user }: {
+        user: Address;
+    }): Promise<number>;
+    isTokenInUserList({ user, token, }: {
+        user: Address;
+        token: Address;
+    }): Promise<boolean>;
+    getUpvotePrice(): Promise<bigint>;
+    upvoteUser({ walletClient, userToUpvote, token, numUpvotes, feeTier, value: providedValue, }: {
+        walletClient: WalletClient;
+        userToUpvote: Address;
+        token?: Address;
+        numUpvotes: number;
+        feeTier?: number;
+        /** Pre-computed ETH value. When omitted, fetches upvotePrice from chain. */
+        value?: bigint;
+    }): Promise<`0x${string}`>;
+}
+
 /**
  * Convert token address to bytes32 upvote key.
  */
@@ -226,5 +338,69 @@ declare const MULTI_VERSION_UNISWAP_POOL_INFO_RETRIEVER: {
 declare function getWethAddress(chainId: number): Address;
 declare const NULL_ADDRESS: Address;
 declare const UPVOTE_PRICE_ETH = 0.000025;
+declare const USER_UPVOTE_CONTRACT: {
+    readonly address: Address;
+    readonly abi: Abi;
+};
+
+/**
+ * Parse a Net protocol message from the user upvote contract.
+ *
+ * Two formats based on topic:
+ * - Topic "ub-{address}" (received upvotes): 7 fields including userTokenBalance
+ * - Topic "g" (given upvotes): 6 fields without userTokenBalance
+ */
+declare function parseUserUpvoteMessage(message: UserUpvoteNetMessage, topic: string): ParsedUserUpvoteMessage | null;
+/**
+ * Extract unique token addresses from an array of Net messages.
+ */
+declare function extractTokenAddressesFromMessages(messages: UserUpvoteNetMessage[], topic: string): TokenAddressExtraction;
+/**
+ * Validate that a Net message can be parsed as a user upvote message.
+ */
+declare function validateUserUpvoteMessage(message: UserUpvoteNetMessage, topic: string): boolean;
+/**
+ * Calculate the USDC price from a parsed user upvote message.
+ *
+ * The contract emits (halfWei * 1e18) / amountRaw for tokenWethPrice,
+ * so we divide by 10^(36 - tokenDecimals) to get the actual price.
+ */
+declare function calculatePriceInUsdc(parsedMessage: ParsedUserUpvoteMessage, tokenDecimals?: number): number | undefined;
+/**
+ * Calculate the human-readable token balance from a raw bigint value.
+ */
+declare function calculateUserTokenBalance(rawBalance: bigint, tokenDecimals?: number): number;
+/**
+ * Client-side validation for upvote parameters.
+ * Mirrors contract-side errors for better UX before sending a transaction.
+ */
+declare function validateUpvoteParams(params: {
+    sender: Address;
+    userToUpvote: Address;
+    numUpvotes: number;
+}): {
+    valid: boolean;
+    error?: string;
+};
+/**
+ * Calculate the total ETH cost for a given number of upvotes.
+ */
+declare function calculateUpvoteCost(numUpvotes: number, upvotePrice: bigint): bigint;
+/**
+ * Build an enriched UserUpvote from a parsed message and optional token info.
+ */
+declare function buildUserUpvote(parsed: ParsedUserUpvoteMessage, timestamp: number, tokenInfo?: {
+    name: string;
+    symbol: string;
+    decimals: number;
+}): UserUpvote;
+/**
+ * Build an enriched UserUpvoteReceived from a parsed message, upvoter address, and optional token info.
+ */
+declare function buildUserUpvoteReceived(parsed: ParsedUserUpvoteMessage, upvoterAddress: string, timestamp: number, tokenInfo?: {
+    name: string;
+    symbol: string;
+    decimals: number;
+}): UserUpvoteReceived;
 
-export { ALL_STRATEGY_ADDRESSES, DYNAMIC_SPLIT_STRATEGY, DecodedStrategyMetadata, GetAppKeyScoresOptions, GetStrategyKeyScoresOptions, GetUpvotesForItemsOptions, GetUpvotesOptions, LEGACY_UPVOTE_V1_ADDRESS, LEGACY_UPVOTE_V2_ADDRESS, MULTI_VERSION_UNISWAP_BULK_POOL_FINDER, MULTI_VERSION_UNISWAP_POOL_INFO_RETRIEVER, NULL_ADDRESS, PURE_ALPHA_STRATEGY, PoolDiscoveryResult, PoolKey, SCORE_CONTRACT, SUPPORTED_SCORE_CHAINS, ScoreClient, ScoreClientOptions, UNIV234_POOLS_STRATEGY, UPVOTE_APP, UPVOTE_PRICE_ETH, UPVOTE_STORAGE_APP, calculatePriceFromSqrtPriceX96, decodeStrategyMetadata, decodeUpvoteMessage, decodeUpvoteStorageBlob, discoverPools, discoverTokenPool, encodePoolKey, encodeUpvoteKey, extractStrategyAddress, getWethAddress, isDynamicSplitStrategy, isPureAlphaStrategy, isStrategyMessage, isUniv234PoolsStrategy, isUserUpvoteMessage, selectStrategy, tokenAddressToUpvoteKeyString };
+export { ALL_STRATEGY_ADDRESSES, DYNAMIC_SPLIT_STRATEGY, DecodedStrategyMetadata, GetAppKeyScoresOptions, GetStrategyKeyScoresOptions, GetUpvotesForItemsOptions, GetUpvotesOptions, LEGACY_UPVOTE_V1_ADDRESS, LEGACY_UPVOTE_V2_ADDRESS, MULTI_VERSION_UNISWAP_BULK_POOL_FINDER, MULTI_VERSION_UNISWAP_POOL_INFO_RETRIEVER, NULL_ADDRESS, PURE_ALPHA_STRATEGY, type ParsedUserUpvoteMessage, PoolDiscoveryResult, PoolKey, SCORE_CONTRACT, SUPPORTED_SCORE_CHAINS, ScoreClient, ScoreClientOptions, type TokenAddressExtraction, UNIV234_POOLS_STRATEGY, UPVOTE_APP, UPVOTE_PRICE_ETH, UPVOTE_STORAGE_APP, USER_UPVOTE_CONTRACT, type UserUpvote, UserUpvoteClient, type UserUpvoteClientOptions, type UserUpvoteNetMessage, type UserUpvoteReceived, buildUserUpvote, buildUserUpvoteReceived, calculatePriceFromSqrtPriceX96, calculatePriceInUsdc, calculateUpvoteCost, calculateUserTokenBalance, decodeStrategyMetadata, decodeUpvoteMessage, decodeUpvoteStorageBlob, discoverPools, discoverTokenPool, encodePoolKey, encodeUpvoteKey, extractStrategyAddress, extractTokenAddressesFromMessages, getWethAddress, isDynamicSplitStrategy, isPureAlphaStrategy, isStrategyMessage, isUniv234PoolsStrategy, isUserUpvoteMessage, parseUserUpvoteMessage, selectStrategy, tokenAddressToUpvoteKeyString, validateUpvoteParams, validateUserUpvoteMessage };

package/dist/index.d.ts

@@ -1,6 +1,6 @@
-import { S as ScoreClientOptions, G as GetUpvotesOptions, a as GetUpvotesForItemsOptions, b as GetStrategyKeyScoresOptions, c as GetAppKeyScoresOptions, D as DecodedStrategyMetadata, P as PoolKey, d as PoolDiscoveryResult } from './scoreKeyUtils-DgHOtf44.js';
-export { e as DecodedUpvoteBlob, F as FeedMessage, f as PoolStrategyMetadata, g as PureAlphaMetadata, h as ScoreItem, U as UseTokenUpvotesOptions, i as UseUpvotesBatchOptions, j as UseUpvotesOptions, k as extractTokenAddressFromScoreKey, l as getFeedContentKey, m as getScoreKey, n as getStorageScoreKey, o as getStorageUpvoteContext, p as getTokenScoreKey, q as isTokenScoreKey } from './scoreKeyUtils-DgHOtf44.js';
-import { Address, PublicClient, Abi } from 'viem';
+import { S as ScoreClientOptions, G as GetUpvotesOptions, a as GetUpvotesForItemsOptions, b as GetStrategyKeyScoresOptions, c as GetAppKeyScoresOptions, D as DecodedStrategyMetadata, P as PoolKey, d as PoolDiscoveryResult } from './scoreKeyUtils-DuH70ypB.js';
+export { e as DecodedUpvoteBlob, F as FeedMessage, f as PoolStrategyMetadata, g as PureAlphaMetadata, h as ScoreItem, U as UseTokenUpvotesOptions, i as UseUpvotePriceOptions, j as UseUpvoteUserOptions, k as UseUpvotesBatchOptions, l as UseUpvotesOptions, m as UseUserUpvotesGivenOptions, n as UseUserUpvotesGivenPerTokenBatchOptions, o as UseUserUpvotesReceivedOptions, p as UseUserUpvotesReceivedPerTokenBatchOptions, q as extractTokenAddressFromScoreKey, r as getFeedContentKey, s as getScoreKey, t as getStorageScoreKey, u as getStorageUpvoteContext, v as getTokenScoreKey, w as isTokenScoreKey } from './scoreKeyUtils-DuH70ypB.js';
+import { Address, WalletClient, PublicClient, Abi } from 'viem';
 
 /**
  * ScoreClient - Client for interacting with Net protocol scoring/upvote system
@@ -37,6 +37,118 @@ declare class ScoreClient {
     getAppKeyScores({ app, scoreKeys, }: GetAppKeyScoresOptions): Promise<number[]>;
 }
 
+type ParsedUserUpvoteMessage = {
+    upvotedUserString: string;
+    actualToken: string;
+    numUpvotes: number;
+    tokenWethPrice: bigint;
+    wethUsdcPrice: bigint;
+    alphaWethPrice: bigint;
+    userTokenBalance?: bigint;
+};
+type TokenAddressExtraction = {
+    tokenAddresses: string[];
+    validMessages: ParsedUserUpvoteMessage[];
+};
+type UserUpvote = {
+    tokenAddress: string;
+    numUpvotes: number;
+    timestamp: number;
+    priceInUsdc?: number;
+    userTokenBalance: number;
+    userTokenBalanceUsdValue?: number;
+    upvotedUserAddress?: string;
+    tokenInfo?: {
+        name: string;
+        symbol: string;
+        decimals: number;
+    };
+};
+type UserUpvoteReceived = {
+    upvoterAddress: string;
+    tokenAddress: string;
+    numUpvotes: number;
+    timestamp: number;
+    priceInUsdc?: number;
+    userTokenBalance: number;
+    userTokenBalanceUsdValue?: number;
+    tokenInfo?: {
+        name: string;
+        symbol: string;
+        decimals: number;
+    };
+};
+type UserUpvoteClientOptions = {
+    chainId: number;
+    overrides?: {
+        contractAddress?: Address;
+        rpcUrls?: string[];
+    };
+};
+type UserUpvoteNetMessage = {
+    app: `0x${string}`;
+    sender: `0x${string}`;
+    timestamp: bigint;
+    data: `0x${string}`;
+    text: string;
+    topic: string;
+};
+
+/**
+ * UserUpvoteClient - Client for reading user-to-user upvote data.
+ *
+ * This is a standalone upvote system separate from the token Score system.
+ * It reads directly from the UserUpvote contract on Base.
+ */
+declare class UserUpvoteClient {
+    private client;
+    private contractAddress;
+    private chainId;
+    constructor(params: UserUpvoteClientOptions);
+    getUserUpvotesGiven({ user }: {
+        user: Address;
+    }): Promise<bigint>;
+    getUserUpvotesReceived({ user }: {
+        user: Address;
+    }): Promise<bigint>;
+    getUserUpvotesGivenPerTokenBatch({ user, tokens, }: {
+        user: Address;
+        tokens: Address[];
+    }): Promise<bigint[]>;
+    getUserUpvotesReceivedPerTokenBatch({ user, tokens, }: {
+        user: Address;
+        tokens: Address[];
+    }): Promise<bigint[]>;
+    getTotalUpvotesPerToken({ token, }: {
+        token: Address;
+    }): Promise<bigint>;
+    getUserTokensInRange({ user, startIndex, endIndex, }: {
+        user: Address;
+        startIndex: number;
+        endIndex: number;
+    }): Promise<{
+        token: Address;
+        feeTier: number;
+    }[]>;
+    getUserTokenCount({ user }: {
+        user: Address;
+    }): Promise<number>;
+    isTokenInUserList({ user, token, }: {
+        user: Address;
+        token: Address;
+    }): Promise<boolean>;
+    getUpvotePrice(): Promise<bigint>;
+    upvoteUser({ walletClient, userToUpvote, token, numUpvotes, feeTier, value: providedValue, }: {
+        walletClient: WalletClient;
+        userToUpvote: Address;
+        token?: Address;
+        numUpvotes: number;
+        feeTier?: number;
+        /** Pre-computed ETH value. When omitted, fetches upvotePrice from chain. */
+        value?: bigint;
+    }): Promise<`0x${string}`>;
+}
+
 /**
  * Convert token address to bytes32 upvote key.
  */
@@ -226,5 +338,69 @@ declare const MULTI_VERSION_UNISWAP_POOL_INFO_RETRIEVER: {
 declare function getWethAddress(chainId: number): Address;
 declare const NULL_ADDRESS: Address;
 declare const UPVOTE_PRICE_ETH = 0.000025;
+declare const USER_UPVOTE_CONTRACT: {
+    readonly address: Address;
+    readonly abi: Abi;
+};
+
+/**
+ * Parse a Net protocol message from the user upvote contract.
+ *
+ * Two formats based on topic:
+ * - Topic "ub-{address}" (received upvotes): 7 fields including userTokenBalance
+ * - Topic "g" (given upvotes): 6 fields without userTokenBalance
+ */
+declare function parseUserUpvoteMessage(message: UserUpvoteNetMessage, topic: string): ParsedUserUpvoteMessage | null;
+/**
+ * Extract unique token addresses from an array of Net messages.
+ */
+declare function extractTokenAddressesFromMessages(messages: UserUpvoteNetMessage[], topic: string): TokenAddressExtraction;
+/**
+ * Validate that a Net message can be parsed as a user upvote message.
+ */
+declare function validateUserUpvoteMessage(message: UserUpvoteNetMessage, topic: string): boolean;
+/**
+ * Calculate the USDC price from a parsed user upvote message.
+ *
+ * The contract emits (halfWei * 1e18) / amountRaw for tokenWethPrice,
+ * so we divide by 10^(36 - tokenDecimals) to get the actual price.
+ */
+declare function calculatePriceInUsdc(parsedMessage: ParsedUserUpvoteMessage, tokenDecimals?: number): number | undefined;
+/**
+ * Calculate the human-readable token balance from a raw bigint value.
+ */
+declare function calculateUserTokenBalance(rawBalance: bigint, tokenDecimals?: number): number;
+/**
+ * Client-side validation for upvote parameters.
+ * Mirrors contract-side errors for better UX before sending a transaction.
+ */
+declare function validateUpvoteParams(params: {
+    sender: Address;
+    userToUpvote: Address;
+    numUpvotes: number;
+}): {
+    valid: boolean;
+    error?: string;
+};
+/**
+ * Calculate the total ETH cost for a given number of upvotes.
+ */
+declare function calculateUpvoteCost(numUpvotes: number, upvotePrice: bigint): bigint;
+/**
+ * Build an enriched UserUpvote from a parsed message and optional token info.
+ */
+declare function buildUserUpvote(parsed: ParsedUserUpvoteMessage, timestamp: number, tokenInfo?: {
+    name: string;
+    symbol: string;
+    decimals: number;
+}): UserUpvote;
+/**
+ * Build an enriched UserUpvoteReceived from a parsed message, upvoter address, and optional token info.
+ */
+declare function buildUserUpvoteReceived(parsed: ParsedUserUpvoteMessage, upvoterAddress: string, timestamp: number, tokenInfo?: {
+    name: string;
+    symbol: string;
+    decimals: number;
+}): UserUpvoteReceived;
 
-export { ALL_STRATEGY_ADDRESSES, DYNAMIC_SPLIT_STRATEGY, DecodedStrategyMetadata, GetAppKeyScoresOptions, GetStrategyKeyScoresOptions, GetUpvotesForItemsOptions, GetUpvotesOptions, LEGACY_UPVOTE_V1_ADDRESS, LEGACY_UPVOTE_V2_ADDRESS, MULTI_VERSION_UNISWAP_BULK_POOL_FINDER, MULTI_VERSION_UNISWAP_POOL_INFO_RETRIEVER, NULL_ADDRESS, PURE_ALPHA_STRATEGY, PoolDiscoveryResult, PoolKey, SCORE_CONTRACT, SUPPORTED_SCORE_CHAINS, ScoreClient, ScoreClientOptions, UNIV234_POOLS_STRATEGY, UPVOTE_APP, UPVOTE_PRICE_ETH, UPVOTE_STORAGE_APP, calculatePriceFromSqrtPriceX96, decodeStrategyMetadata, decodeUpvoteMessage, decodeUpvoteStorageBlob, discoverPools, discoverTokenPool, encodePoolKey, encodeUpvoteKey, extractStrategyAddress, getWethAddress, isDynamicSplitStrategy, isPureAlphaStrategy, isStrategyMessage, isUniv234PoolsStrategy, isUserUpvoteMessage, selectStrategy, tokenAddressToUpvoteKeyString };
+export { ALL_STRATEGY_ADDRESSES, DYNAMIC_SPLIT_STRATEGY, DecodedStrategyMetadata, GetAppKeyScoresOptions, GetStrategyKeyScoresOptions, GetUpvotesForItemsOptions, GetUpvotesOptions, LEGACY_UPVOTE_V1_ADDRESS, LEGACY_UPVOTE_V2_ADDRESS, MULTI_VERSION_UNISWAP_BULK_POOL_FINDER, MULTI_VERSION_UNISWAP_POOL_INFO_RETRIEVER, NULL_ADDRESS, PURE_ALPHA_STRATEGY, type ParsedUserUpvoteMessage, PoolDiscoveryResult, PoolKey, SCORE_CONTRACT, SUPPORTED_SCORE_CHAINS, ScoreClient, ScoreClientOptions, type TokenAddressExtraction, UNIV234_POOLS_STRATEGY, UPVOTE_APP, UPVOTE_PRICE_ETH, UPVOTE_STORAGE_APP, USER_UPVOTE_CONTRACT, type UserUpvote, UserUpvoteClient, type UserUpvoteClientOptions, type UserUpvoteNetMessage, type UserUpvoteReceived, buildUserUpvote, buildUserUpvoteReceived, calculatePriceFromSqrtPriceX96, calculatePriceInUsdc, calculateUpvoteCost, calculateUserTokenBalance, decodeStrategyMetadata, decodeUpvoteMessage, decodeUpvoteStorageBlob, discoverPools, discoverTokenPool, encodePoolKey, encodeUpvoteKey, extractStrategyAddress, extractTokenAddressesFromMessages, getWethAddress, isDynamicSplitStrategy, isPureAlphaStrategy, isStrategyMessage, isUniv234PoolsStrategy, isUserUpvoteMessage, parseUserUpvoteMessage, selectStrategy, tokenAddressToUpvoteKeyString, validateUpvoteParams, validateUserUpvoteMessage };