Merge pull request #7 from Cygnus-Wealth/merge/refinery/da-a22a

feat: add decentralized RPC provider and privacy types

Author: linuxninja39

etc/data-models.api.md

@@ -510,6 +510,13 @@ export interface Price {
     value?: number;
 }
 
+// @public
+export interface PrivacyConfig {
+    privacyMode: boolean;
+    queryJitterMs: number;
+    rotateWithinTier: boolean;
+}
+
 // @public
 export interface RetryConfig {
     baseDelayMs: number;
@@ -534,7 +541,9 @@ export interface RpcProviderConfig {
     chains: Record<string, ChainRpcConfig>;
     circuitBreaker: CircuitBreakerConfig;
     healthCheck: HealthCheckConfig;
+    privacy: PrivacyConfig;
     retry: RetryConfig;
+    userOverrides?: UserRpcConfig;
 }
 
 // @public
@@ -548,8 +557,10 @@ export enum RpcProviderRole {
 // @public
 export enum RpcProviderType {
     COMMUNITY = "COMMUNITY",
+    DECENTRALIZED = "DECENTRALIZED",
     MANAGED = "MANAGED",
-    PUBLIC = "PUBLIC"
+    PUBLIC = "PUBLIC",
+    USER = "USER"
 }
 
 // @public
@@ -656,6 +667,20 @@ export enum TransactionType {
     UNSTAKE = "UNSTAKE"
 }
 
+// @public
+export interface UserRpcConfig {
+    endpoints: UserRpcEndpoint[];
+    mode: 'override' | 'prepend';
+}
+
+// @public
+export interface UserRpcEndpoint {
+    chainId: string;
+    label?: string;
+    url: string;
+    wsUrl?: string;
+}
+
 // @public
 export interface VaultPosition {
     apy?: number;

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cygnus-wealth/data-models",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "Shared TypeScript data models for CygnusWealth project",
   "main": "dist/cjs/index.js",
   "module": "dist/index.js",

src/enums/RpcProviderType.ts

@@ -28,5 +28,11 @@ export enum RpcProviderType {
   PUBLIC = 'PUBLIC',
 
   /** Community-run node (POKT, Llama Nodes) — variable reliability */
-  COMMUNITY = 'COMMUNITY'
+  COMMUNITY = 'COMMUNITY',
+
+  /** Decentralized RPC network (POKT Gateway, Lava Network) — censorship-resistant */
+  DECENTRALIZED = 'DECENTRALIZED',
+
+  /** User-provided custom endpoint — unverified, user-managed */
+  USER = 'USER'
 }

src/index.ts

@@ -87,6 +87,9 @@ export { CircuitBreakerConfig } from './interfaces/CircuitBreakerConfig';
 export { RetryConfig } from './interfaces/RetryConfig';
 export { HealthCheckConfig } from './interfaces/HealthCheckConfig';
 export { RpcProviderConfig } from './interfaces/RpcProviderConfig';
+export type { UserRpcEndpoint } from './interfaces/UserRpcEndpoint';
+export type { UserRpcConfig } from './interfaces/UserRpcConfig';
+export type { PrivacyConfig } from './interfaces/PrivacyConfig';
 
 // Network Environment
 export { NetworkEnvironment, EnvironmentConfig } from './types/NetworkEnvironment';

src/interfaces/PrivacyConfig.ts

@@ -0,0 +1,32 @@
+/**
+ * Privacy-related configuration for RPC request handling.
+ *
+ * Controls endpoint rotation and query obfuscation strategies to
+ * reduce correlation of user activity across RPC providers.
+ *
+ * @example
+ * ```typescript
+ * import type { PrivacyConfig } from '@cygnus-wealth/data-models';
+ *
+ * const privacy: PrivacyConfig = {
+ *   rotateWithinTier: true,
+ *   privacyMode: true,
+ *   queryJitterMs: 150
+ * };
+ * ```
+ *
+ * @since 1.3.0
+ * @stability extended
+ *
+ * @see {@link RpcProviderConfig} for top-level usage
+ */
+export interface PrivacyConfig {
+  /** Rotate between endpoints of the same tier/role to avoid fingerprinting */
+  rotateWithinTier: boolean;
+
+  /** Enable full privacy mode (distributes queries across providers) */
+  privacyMode: boolean;
+
+  /** Random jitter added to query timing to resist timing analysis (in milliseconds) */
+  queryJitterMs: number;
+}

src/interfaces/RpcProviderConfig.ts

@@ -2,6 +2,8 @@ import { ChainRpcConfig } from './ChainRpcConfig';
 import { CircuitBreakerConfig } from './CircuitBreakerConfig';
 import { RetryConfig } from './RetryConfig';
 import { HealthCheckConfig } from './HealthCheckConfig';
+import { PrivacyConfig } from './PrivacyConfig';
+import { UserRpcConfig } from './UserRpcConfig';
 
 /**
  * Top-level RPC provider configuration for multi-chain operations.
@@ -57,6 +59,8 @@ import { HealthCheckConfig } from './HealthCheckConfig';
  * @see {@link CircuitBreakerConfig} for failure isolation policy
  * @see {@link RetryConfig} for retry strategy
  * @see {@link HealthCheckConfig} for endpoint monitoring
+ * @see {@link PrivacyConfig} for privacy and rotation policy
+ * @see {@link UserRpcConfig} for user-provided endpoint overrides
  */
 export interface RpcProviderConfig {
   /** Per-chain RPC configurations, keyed by chain ID string (e.g. "1", "137") */
@@ -70,4 +74,10 @@ export interface RpcProviderConfig {
 
   /** Health check policy for endpoint monitoring */
   healthCheck: HealthCheckConfig;
+
+  /** Privacy and endpoint rotation policy */
+  privacy: PrivacyConfig;
+
+  /** Optional user-provided RPC endpoint overrides */
+  userOverrides?: UserRpcConfig;
 }

src/interfaces/UserRpcConfig.ts

@@ -0,0 +1,36 @@
+import { UserRpcEndpoint } from './UserRpcEndpoint';
+
+/**
+ * Configuration for user-provided RPC endpoint overrides.
+ *
+ * Determines how user-supplied endpoints interact with the
+ * platform-managed endpoint list. In 'override' mode, user endpoints
+ * completely replace managed endpoints for the given chains. In
+ * 'prepend' mode, user endpoints are tried first before falling back
+ * to managed endpoints.
+ *
+ * @example
+ * ```typescript
+ * import type { UserRpcConfig } from '@cygnus-wealth/data-models';
+ *
+ * const userConfig: UserRpcConfig = {
+ *   endpoints: [
+ *     { chainId: '1', url: 'https://my-eth.example.com/rpc', label: 'My ETH' }
+ *   ],
+ *   mode: 'prepend'
+ * };
+ * ```
+ *
+ * @since 1.3.0
+ * @stability extended
+ *
+ * @see {@link UserRpcEndpoint} for individual endpoint definition
+ * @see {@link RpcProviderConfig} for top-level usage
+ */
+export interface UserRpcConfig {
+  /** List of user-provided RPC endpoints */
+  endpoints: UserRpcEndpoint[];
+
+  /** How user endpoints interact with managed endpoints: 'override' replaces, 'prepend' adds before */
+  mode: 'override' | 'prepend';
+}

src/interfaces/UserRpcEndpoint.ts

@@ -0,0 +1,37 @@
+/**
+ * A user-provided custom RPC endpoint configuration.
+ *
+ * Represents an RPC endpoint supplied by the end user, enabling
+ * self-sovereign infrastructure choices. These endpoints are not
+ * managed or verified by the platform.
+ *
+ * @example
+ * ```typescript
+ * import type { UserRpcEndpoint } from '@cygnus-wealth/data-models';
+ *
+ * const myNode: UserRpcEndpoint = {
+ *   chainId: '1',
+ *   url: 'https://my-private-node.example.com/rpc',
+ *   wsUrl: 'wss://my-private-node.example.com/ws',
+ *   label: 'My Private Ethereum Node'
+ * };
+ * ```
+ *
+ * @since 1.3.0
+ * @stability extended
+ *
+ * @see {@link UserRpcConfig} for aggregating user endpoints
+ */
+export interface UserRpcEndpoint {
+  /** Target chain ID as a string (e.g. "1", "137") */
+  chainId: string;
+
+  /** HTTP(S) RPC endpoint URL */
+  url: string;
+
+  /** Optional WebSocket endpoint URL for subscriptions */
+  wsUrl?: string;
+
+  /** Optional human-readable label for the endpoint */
+  label?: string;
+}