@net-protocol/score 0.1.0 → 0.1.1

package/README.md

@@ -0,0 +1,229 @@
+# @net-protocol/score
+
+**Status: In Development** - This package is under active development. APIs may change without notice.
+
+SDK for the Net Score system - an on-chain scoring/upvoting system for tokens, storage entries, and feed posts on Net Protocol.
+
+## What is Net Score?
+
+Net Score is a decentralized on-chain scoring system built on Net Protocol. It allows users to upvote content (tokens, storage entries, feed posts) using strategy-based voting where vote weight is derived from on-chain holdings.
+
+**Key features:**
+- **Token Upvotes**: Upvote tokens by address
+- **Storage Upvotes**: Upvote storage entries by operator and key
+- **Feed Upvotes**: Upvote feed posts by content
+- **Strategy-Based Voting**: Vote weight is determined by on-chain strategies (Alpha holdings, Uniswap pool positions, or configurable splits)
+- **Legacy Support**: Aggregates scores across legacy upvote contracts and current strategies
+
+## What can you do with this package?
+
+- **Read upvote counts** for tokens, storage entries, and feed posts
+- **Batch-read upvotes** for multiple items in a single contract call
+- **Query scores by strategy** to see per-strategy breakdowns
+- **Query scores by app** for app-specific score data
+- **Generate score keys** for any scoreable item type
+- **Decode upvote messages** from Net protocol (legacy and strategy formats)
+- **Decode strategy metadata** to inspect vote weight details
+- **Select strategies** automatically based on pool key availability
+
+This package provides both React hooks (for UI) and a client class (for non-React code).
+
+## Installation
+
+```bash
+npm install @net-protocol/score @net-protocol/core @net-protocol/storage viem
+# or
+yarn add @net-protocol/score @net-protocol/core @net-protocol/storage viem
+```
+
+For React hooks, also install:
+```bash
+npm install react wagmi @tanstack/react-query
+```
+
+## Usage
+
+### React Hooks
+
+```typescript
+import { useTokenUpvotes, useUpvotes, useUpvotesBatch } from "@net-protocol/score/react";
+import { getTokenScoreKey, getStorageScoreKey } from "@net-protocol/score/react";
+
+// Get upvotes for a single token
+function TokenScore({ tokenAddress }: { tokenAddress: string }) {
+  const { upvotes, isLoading } = useTokenUpvotes({
+    chainId: 8453,
+    tokenAddress,
+  });
+
+  if (isLoading) return <div>Loading...</div>;
+  return <div>Upvotes: {upvotes}</div>;
+}
+
+// Get upvotes for a single score key
+function ScoreKeyUpvotes({ scoreKey }: { scoreKey: `0x${string}` }) {
+  const { upvotes, isLoading } = useUpvotes({
+    chainId: 8453,
+    scoreKey,
+  });
+
+  return <div>{isLoading ? "..." : upvotes}</div>;
+}
+
+// Batch-read upvotes for multiple items
+function BatchScores() {
+  const { upvoteCounts, isLoading } = useUpvotesBatch({
+    chainId: 8453,
+    items: [
+      { type: "token", tokenAddress: "0x..." },
+      { type: "storage", operatorAddress: "0x...", storageKey: "my-key" },
+    ],
+  });
+
+  return (
+    <div>
+      {upvoteCounts.map((count, i) => (
+        <div key={i}>Item {i}: {count} upvotes</div>
+      ))}
+    </div>
+  );
+}
+```
+
+### ScoreClient (Non-React)
+
+```typescript
+import { ScoreClient } from "@net-protocol/score";
+import { getTokenScoreKey, getStorageScoreKey } from "@net-protocol/score";
+
+const client = new ScoreClient({ chainId: 8453 });
+
+// Get upvote counts for token score keys
+const tokenKey = getTokenScoreKey("0x...");
+const counts = await client.getUpvotesWithLegacy({
+  scoreKeys: [tokenKey],
+});
+console.log("Upvotes:", counts[0]);
+
+// Batch upvotes for mixed item types
+const batchCounts = await client.getUpvotesForItems({
+  items: [
+    { type: "token", tokenAddress: "0x..." },
+    { type: "storage", operatorAddress: "0x...", storageKey: "my-key" },
+  ],
+});
+
+// Query scores from a specific strategy
+import { PURE_ALPHA_STRATEGY } from "@net-protocol/score";
+
+const strategyCounts = await client.getStrategyKeyScores({
+  strategy: PURE_ALPHA_STRATEGY.address,
+  scoreKeys: [tokenKey],
+});
+
+// Query scores from a specific app
+const appCounts = await client.getAppKeyScores({
+  app: "0x...",
+  scoreKeys: [tokenKey],
+});
+```
+
+## API Reference
+
+### ScoreClient
+
+| Method | Description |
+|--------|-------------|
+| `getUpvotesWithLegacy(opts)` | Get upvote counts for score keys, aggregated across legacy contracts and strategies |
+| `getUpvotesForItems(opts)` | Get upvote counts for an array of `ScoreItem` objects |
+| `getStrategyKeyScores(opts)` | Get scores for keys from a specific strategy |
+| `getAppKeyScores(opts)` | Get scores for keys from a specific app |
+
+### React Hooks
+
+| Hook | Description |
+|------|-------------|
+| `useTokenUpvotes(opts)` | Get upvote count for a single token address |
+| `useUpvotes(opts)` | Get upvote count for a single score key |
+| `useUpvotesBatch(opts)` | Get upvote counts for multiple items in one call |
+
+### Score Key Utilities
+
+| Function | Description |
+|----------|-------------|
+| `getTokenScoreKey(tokenAddress)` | Generate score key for a token |
+| `getStorageScoreKey(operatorAddress, storageKey)` | Generate score key for a storage entry |
+| `getFeedContentKey(message)` | Generate content key for a feed post |
+| `getScoreKey(item)` | Generate score key for any `ScoreItem` |
+| `isTokenScoreKey(scoreKey)` | Check if a score key represents a token |
+| `extractTokenAddressFromScoreKey(scoreKey)` | Extract token address from a token score key |
+| `getStorageUpvoteContext(operatorAddress, storageKey)` | Generate upvote stored context for storage upvotes |
+
+### Strategy Utilities
+
+| Function | Description |
+|----------|-------------|
+| `selectStrategy(poolKey?)` | Select appropriate strategy based on pool key |
+| `decodeStrategyMetadata(metadata, strategyAddress)` | Decode strategy-specific metadata |
+| `decodeUpvoteStorageBlob(value)` | Decode a full Score storage blob |
+| `decodeUpvoteMessage(msg)` | Decode an upvote message (legacy and strategy formats) |
+| `encodePoolKey(poolKey?)` | Encode a PoolKey struct to bytes |
+
+### Types
+
+```typescript
+// Scoreable item (discriminated union)
+type ScoreItem =
+  | { type: "token"; tokenAddress: string }
+  | { type: "storage"; operatorAddress: string; storageKey: string }
+  | { type: "feed"; message: FeedMessage };
+
+type FeedMessage = {
+  app: Address;
+  sender: Address;
+  timestamp: bigint;
+  data: `0x${string}`;
+  text: string;
+  topic: string;
+};
+
+// Client options
+type ScoreClientOptions = {
+  chainId: number;
+  overrides?: {
+    scoreAddress?: Address;
+    upvoteAppAddress?: Address;
+    rpcUrls?: string[];
+  };
+};
+```
+
+### Strategies
+
+The Score system supports multiple voting strategies that determine vote weight:
+
+| Strategy | Constant | Description |
+|----------|----------|-------------|
+| Pure Alpha | `PURE_ALPHA_STRATEGY` | Vote weight based on Alpha token holdings |
+| Uni V2/V3/V4 Pools | `UNIV234_POOLS_STRATEGY` | Vote weight based on Uniswap pool positions |
+| Dynamic Split | `DYNAMIC_SPLIT_STRATEGY` | Configurable token/alpha split for pool positions |
+
+### Constants
+
+| Constant | Description |
+|----------|-------------|
+| `SCORE_CONTRACT` | Score core contract address and ABI |
+| `UPVOTE_APP` | UpvoteApp contract address and ABI |
+| `UPVOTE_STORAGE_APP` | UpvoteStorageApp contract address and ABI |
+| `ALL_STRATEGY_ADDRESSES` | Array of all strategy contract addresses |
+| `SUPPORTED_SCORE_CHAINS` | Chains where Score is deployed |
+
+## Supported Chains
+
+| Chain | Chain ID | Status |
+|-------|----------|--------|
+| Base | 8453 | Supported |
+
+## License
+
+MIT

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 } from './scoreKeyUtils-DIjbizO-.mjs';
-export { n as DecodedUpvoteBlob, F as FeedMessage, m as PoolStrategyMetadata, l as PureAlphaMetadata, k as ScoreItem, p as UseTokenUpvotesOptions, o as UseUpvotesBatchOptions, U as UseUpvotesOptions, h as extractTokenAddressFromScoreKey, e as getFeedContentKey, f as getScoreKey, d as getStorageScoreKey, j as getStorageUpvoteContext, g as getTokenScoreKey, i as isTokenScoreKey } from './scoreKeyUtils-DIjbizO-.mjs';
-import { Address, 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-Dn43l8hQ.mjs';
+export { o as DecodedUpvoteBlob, F as FeedMessage, n as PoolStrategyMetadata, m as PureAlphaMetadata, l as ScoreItem, q as UseTokenUpvotesOptions, p as UseUpvotesBatchOptions, U as UseUpvotesOptions, j as extractTokenAddressFromScoreKey, f as getFeedContentKey, h as getScoreKey, e as getStorageScoreKey, k as getStorageUpvoteContext, g as getTokenScoreKey, i as isTokenScoreKey } from './scoreKeyUtils-Dn43l8hQ.mjs';
+import { Address, PublicClient, Abi } from 'viem';
 
 /**
  * ScoreClient - Client for interacting with Net protocol scoring/upvote system
@@ -156,6 +156,30 @@ declare function decodeUpvoteMessage(msg: {
  */
 declare const encodePoolKey: (poolKey?: PoolKey | null) => `0x${string}`;
 
+/**
+ * Calculate price from sqrtPriceX96 for Uniswap V3/V4 pools.
+ */
+declare function calculatePriceFromSqrtPriceX96(sqrtPriceX96: bigint, token0Decimals: number, token1Decimals: number, isToken0: boolean): number;
+/**
+ * Discover the best Uniswap pools for multiple token pairs.
+ * Makes two on-chain calls: pool discovery + pool info retrieval.
+ */
+declare function discoverPools({ publicClient, pairs, }: {
+    publicClient: PublicClient;
+    pairs: {
+        tokenAddress: string;
+        baseTokenAddress?: string;
+    }[];
+}): Promise<PoolDiscoveryResult[]>;
+/**
+ * Discover the best WETH pool for a single token.
+ * Convenience wrapper around discoverPools.
+ */
+declare function discoverTokenPool({ publicClient, tokenAddress, }: {
+    publicClient: PublicClient;
+    tokenAddress: string;
+}): Promise<PoolDiscoveryResult | null>;
+
 declare const SCORE_CONTRACT: {
     readonly address: Address;
     readonly abi: Abi;
@@ -184,5 +208,16 @@ declare const ALL_STRATEGY_ADDRESSES: Address[];
 declare const LEGACY_UPVOTE_V1_ADDRESS: Address;
 declare const LEGACY_UPVOTE_V2_ADDRESS: Address;
 declare const SUPPORTED_SCORE_CHAINS: readonly [8453];
+declare const MULTI_VERSION_UNISWAP_BULK_POOL_FINDER: {
+    readonly address: Address;
+    readonly abi: Abi;
+};
+declare const MULTI_VERSION_UNISWAP_POOL_INFO_RETRIEVER: {
+    readonly address: Address;
+    readonly abi: Abi;
+};
+declare const WETH_ADDRESS: Address;
+declare const NULL_ADDRESS: Address;
+declare const UPVOTE_PRICE_ETH = 0.000025;
 
-export { ALL_STRATEGY_ADDRESSES, DYNAMIC_SPLIT_STRATEGY, DecodedStrategyMetadata, GetAppKeyScoresOptions, GetStrategyKeyScoresOptions, GetUpvotesForItemsOptions, GetUpvotesOptions, LEGACY_UPVOTE_V1_ADDRESS, LEGACY_UPVOTE_V2_ADDRESS, PURE_ALPHA_STRATEGY, PoolKey, SCORE_CONTRACT, SUPPORTED_SCORE_CHAINS, ScoreClient, ScoreClientOptions, UNIV234_POOLS_STRATEGY, UPVOTE_APP, UPVOTE_STORAGE_APP, decodeStrategyMetadata, decodeUpvoteMessage, decodeUpvoteStorageBlob, encodePoolKey, encodeUpvoteKey, extractStrategyAddress, 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, PoolDiscoveryResult, PoolKey, SCORE_CONTRACT, SUPPORTED_SCORE_CHAINS, ScoreClient, ScoreClientOptions, UNIV234_POOLS_STRATEGY, UPVOTE_APP, UPVOTE_PRICE_ETH, UPVOTE_STORAGE_APP, WETH_ADDRESS, calculatePriceFromSqrtPriceX96, decodeStrategyMetadata, decodeUpvoteMessage, decodeUpvoteStorageBlob, discoverPools, discoverTokenPool, encodePoolKey, encodeUpvoteKey, extractStrategyAddress, isDynamicSplitStrategy, isPureAlphaStrategy, isStrategyMessage, isUniv234PoolsStrategy, isUserUpvoteMessage, selectStrategy, tokenAddressToUpvoteKeyString };

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 } from './scoreKeyUtils-DIjbizO-.js';
-export { n as DecodedUpvoteBlob, F as FeedMessage, m as PoolStrategyMetadata, l as PureAlphaMetadata, k as ScoreItem, p as UseTokenUpvotesOptions, o as UseUpvotesBatchOptions, U as UseUpvotesOptions, h as extractTokenAddressFromScoreKey, e as getFeedContentKey, f as getScoreKey, d as getStorageScoreKey, j as getStorageUpvoteContext, g as getTokenScoreKey, i as isTokenScoreKey } from './scoreKeyUtils-DIjbizO-.js';
-import { Address, 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-Dn43l8hQ.js';
+export { o as DecodedUpvoteBlob, F as FeedMessage, n as PoolStrategyMetadata, m as PureAlphaMetadata, l as ScoreItem, q as UseTokenUpvotesOptions, p as UseUpvotesBatchOptions, U as UseUpvotesOptions, j as extractTokenAddressFromScoreKey, f as getFeedContentKey, h as getScoreKey, e as getStorageScoreKey, k as getStorageUpvoteContext, g as getTokenScoreKey, i as isTokenScoreKey } from './scoreKeyUtils-Dn43l8hQ.js';
+import { Address, PublicClient, Abi } from 'viem';
 
 /**
  * ScoreClient - Client for interacting with Net protocol scoring/upvote system
@@ -156,6 +156,30 @@ declare function decodeUpvoteMessage(msg: {
  */
 declare const encodePoolKey: (poolKey?: PoolKey | null) => `0x${string}`;
 
+/**
+ * Calculate price from sqrtPriceX96 for Uniswap V3/V4 pools.
+ */
+declare function calculatePriceFromSqrtPriceX96(sqrtPriceX96: bigint, token0Decimals: number, token1Decimals: number, isToken0: boolean): number;
+/**
+ * Discover the best Uniswap pools for multiple token pairs.
+ * Makes two on-chain calls: pool discovery + pool info retrieval.
+ */
+declare function discoverPools({ publicClient, pairs, }: {
+    publicClient: PublicClient;
+    pairs: {
+        tokenAddress: string;
+        baseTokenAddress?: string;
+    }[];
+}): Promise<PoolDiscoveryResult[]>;
+/**
+ * Discover the best WETH pool for a single token.
+ * Convenience wrapper around discoverPools.
+ */
+declare function discoverTokenPool({ publicClient, tokenAddress, }: {
+    publicClient: PublicClient;
+    tokenAddress: string;
+}): Promise<PoolDiscoveryResult | null>;
+
 declare const SCORE_CONTRACT: {
     readonly address: Address;
     readonly abi: Abi;
@@ -184,5 +208,16 @@ declare const ALL_STRATEGY_ADDRESSES: Address[];
 declare const LEGACY_UPVOTE_V1_ADDRESS: Address;
 declare const LEGACY_UPVOTE_V2_ADDRESS: Address;
 declare const SUPPORTED_SCORE_CHAINS: readonly [8453];
+declare const MULTI_VERSION_UNISWAP_BULK_POOL_FINDER: {
+    readonly address: Address;
+    readonly abi: Abi;
+};
+declare const MULTI_VERSION_UNISWAP_POOL_INFO_RETRIEVER: {
+    readonly address: Address;
+    readonly abi: Abi;
+};
+declare const WETH_ADDRESS: Address;
+declare const NULL_ADDRESS: Address;
+declare const UPVOTE_PRICE_ETH = 0.000025;
 
-export { ALL_STRATEGY_ADDRESSES, DYNAMIC_SPLIT_STRATEGY, DecodedStrategyMetadata, GetAppKeyScoresOptions, GetStrategyKeyScoresOptions, GetUpvotesForItemsOptions, GetUpvotesOptions, LEGACY_UPVOTE_V1_ADDRESS, LEGACY_UPVOTE_V2_ADDRESS, PURE_ALPHA_STRATEGY, PoolKey, SCORE_CONTRACT, SUPPORTED_SCORE_CHAINS, ScoreClient, ScoreClientOptions, UNIV234_POOLS_STRATEGY, UPVOTE_APP, UPVOTE_STORAGE_APP, decodeStrategyMetadata, decodeUpvoteMessage, decodeUpvoteStorageBlob, encodePoolKey, encodeUpvoteKey, extractStrategyAddress, 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, PoolDiscoveryResult, PoolKey, SCORE_CONTRACT, SUPPORTED_SCORE_CHAINS, ScoreClient, ScoreClientOptions, UNIV234_POOLS_STRATEGY, UPVOTE_APP, UPVOTE_PRICE_ETH, UPVOTE_STORAGE_APP, WETH_ADDRESS, calculatePriceFromSqrtPriceX96, decodeStrategyMetadata, decodeUpvoteMessage, decodeUpvoteStorageBlob, discoverPools, discoverTokenPool, encodePoolKey, encodeUpvoteKey, extractStrategyAddress, isDynamicSplitStrategy, isPureAlphaStrategy, isStrategyMessage, isUniv234PoolsStrategy, isUserUpvoteMessage, selectStrategy, tokenAddressToUpvoteKeyString };