feat: add decentralized RPC provider and privacy types

Extend RpcProviderType enum with DECENTRALIZED and USER values. Add
UserRpcEndpoint, UserRpcConfig, and PrivacyConfig interfaces. Extend
RpcProviderConfig with privacy and userOverrides fields. Bump to v1.3.0.

Phase 1 of en-tfkn (Decentralized RPC Provider Strategy).

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;
+}