@cygnus-wealth/data-models 1.2.0 → 1.4.0

package/dist/interfaces/FilterOptions.d.ts

@@ -1,6 +1,8 @@
 import { Chain } from '../enums/Chain';
 import { AssetType } from '../enums/AssetType';
 import { IntegrationSource } from '../enums/IntegrationSource';
+import { AccountId } from '../types/AccountId';
+import { WalletConnectionId } from '../types/WalletConnectionId';
 import { TimeRange } from '../types/TimeRange';
 /**
  * Flexible filtering criteria for portfolio and transaction queries.
@@ -77,4 +79,10 @@ export interface FilterOptions {
     minValue?: number;
     /** Maximum value threshold (inclusive, in base currency like USD) */
     maxValue?: number;
+    /** Filter by account identifiers (OR within array) */
+    accountIds?: AccountId[];
+    /** Filter by wallet connection identifiers (OR within array) */
+    walletConnectionIds?: WalletConnectionId[];
+    /** Filter by account group identifiers (OR within array) */
+    groupIds?: string[];
 }

package/dist/interfaces/GroupPortfolio.d.ts

@@ -0,0 +1,39 @@
+import { AccountPortfolio } from './AccountPortfolio';
+import { Price } from './Price';
+/**
+ * Portfolio slice for a user-defined account group.
+ *
+ * Aggregates holdings across all accounts in a group, which may span
+ * multiple wallet connections and watch addresses.
+ *
+ * @example
+ * ```typescript
+ * import { GroupPortfolio } from '@cygnus-wealth/data-models';
+ *
+ * const groupPortfolio: GroupPortfolio = {
+ *   groupId: 'group-defi-1',
+ *   groupName: 'DeFi Accounts',
+ *   accounts: [],
+ *   totalValue: { value: 75000, currency: 'USD', timestamp: new Date() },
+ *   lastUpdated: '2026-02-19T08:00:00Z'
+ * };
+ * ```
+ *
+ * @since 1.3.0
+ * @stability extended
+ *
+ * @see {@link AccountGroup} for group definition
+ * @see {@link AccountPortfolio} for per-account breakdown
+ */
+export interface GroupPortfolio {
+    /** Group identifier */
+    groupId: string;
+    /** User-assigned group name */
+    groupName: string;
+    /** Per-account portfolio breakdowns within this group */
+    accounts: AccountPortfolio[];
+    /** Total value across all accounts in this group */
+    totalValue: Price;
+    /** ISO 8601 timestamp of last data update */
+    lastUpdated: string;
+}

package/dist/interfaces/GroupPortfolio.js

@@ -0,0 +1 @@
+export {};

package/dist/interfaces/IntegrationCredentials.d.ts

@@ -1,4 +1,5 @@
 import { IntegrationSource } from '../enums/IntegrationSource';
+import { AccountId } from '../types/AccountId';
 import { Metadata } from './Metadata';
 /**
  * Encrypted credentials for CEX/brokerage API integration.
@@ -60,6 +61,8 @@ export interface IntegrationCredentials {
     walletAddress?: string;
     /** Blockchain network ID for wallet connections (e.g., '1' for Ethereum mainnet) */
     chainId?: string;
+    /** Account identifier when this integration is account-specific */
+    accountId?: AccountId;
     /** Source-specific metadata (permissions, connection settings, etc.) */
     metadata?: Metadata;
 }

package/dist/interfaces/LendingPosition.d.ts

@@ -1,5 +1,6 @@
 import { Chain } from '../enums/Chain';
 import { LendingPositionType } from '../enums/LendingPositionType';
+import { DeFiDiscoverySource } from '../enums/DeFiDiscoverySource';
 import { Asset } from './Asset';
 import { Price } from './Price';
 import { Metadata } from './Metadata';
@@ -98,6 +99,8 @@ export interface LendingPosition {
     liquidationThreshold?: number;
     /** Current total value of position (positive for supply, negative for borrow debt) */
     value?: Price;
+    /** How this position was discovered during portfolio scanning */
+    discoverySource?: DeFiDiscoverySource;
     /** Protocol-specific metadata (collateral assets, liquidation price, etc.) */
     metadata?: Metadata;
 }

package/dist/interfaces/LiquidityPosition.d.ts

@@ -1,4 +1,5 @@
 import { Chain } from '../enums/Chain';
+import { DeFiDiscoverySource } from '../enums/DeFiDiscoverySource';
 import { Balance } from './Balance';
 import { Price } from './Price';
 import { Metadata } from './Metadata';
@@ -77,6 +78,8 @@ export interface LiquidityPosition {
     feesEarned?: number;
     /** Impermanent loss compared to holding tokens (negative = loss, positive = gain) */
     impermanentLoss?: number;
+    /** How this position was discovered during portfolio scanning */
+    discoverySource?: DeFiDiscoverySource;
     /** Protocol-specific metadata (pool version, fee tier, range bounds, etc.) */
     metadata?: Metadata;
 }

package/dist/interfaces/Portfolio.d.ts

@@ -1,4 +1,8 @@
+import { AccountId } from '../types/AccountId';
+import { WalletConnectionId } from '../types/WalletConnectionId';
 import { Account } from './Account';
+import { AccountPortfolio } from './AccountPortfolio';
+import { WalletPortfolio } from './WalletPortfolio';
 import { Price } from './Price';
 import { PortfolioAsset } from './PortfolioAsset';
 import { Metadata } from './Metadata';
@@ -118,6 +122,10 @@ export interface Portfolio {
     };
     /** Timestamp of last portfolio data update */
     lastUpdated: Date;
+    /** Per-account portfolio breakdown for multi-wallet attribution */
+    accountBreakdown?: Map<AccountId, AccountPortfolio>;
+    /** Per-wallet portfolio breakdown for multi-wallet attribution */
+    walletBreakdown?: Map<WalletConnectionId, WalletPortfolio>;
     /** Portfolio-specific metadata (theme, display preferences, etc.) */
     metadata?: Metadata;
 }

package/dist/interfaces/StakedPosition.d.ts

@@ -1,4 +1,5 @@
 import { Chain } from '../enums/Chain';
+import { DeFiDiscoverySource } from '../enums/DeFiDiscoverySource';
 import { Asset } from './Asset';
 import { Balance } from './Balance';
 import { Price } from './Price';
@@ -91,6 +92,8 @@ export interface StakedPosition {
     apr?: number;
     /** Current total value of staked position plus rewards */
     value?: Price;
+    /** How this position was discovered during portfolio scanning */
+    discoverySource?: DeFiDiscoverySource;
     /** Protocol-specific metadata (validator performance, slashing history, etc.) */
     metadata?: Metadata;
 }

package/dist/interfaces/TrackedAddress.d.ts

@@ -0,0 +1,50 @@
+import { AccountId } from '../types/AccountId';
+import { WalletConnectionId } from '../types/WalletConnectionId';
+import { WalletProviderId } from '../types/WalletProviderId';
+import { Chain } from '../enums/Chain';
+import { ChainFamily } from '../enums/ChainFamily';
+/**
+ * An address being tracked for portfolio purposes with full account context.
+ *
+ * Used by the WalletIntegrationContract to communicate tracked addresses
+ * to PortfolioAggregation with all necessary attribution metadata.
+ *
+ * @example
+ * ```typescript
+ * import { TrackedAddress } from '@cygnus-wealth/data-models';
+ *
+ * const tracked: TrackedAddress = {
+ *   accountId: 'metamask:a1b2c3d4:0xAbCdEf1234567890',
+ *   address: '0xAbCdEf1234567890',
+ *   walletConnectionId: 'metamask:a1b2c3d4',
+ *   providerId: 'metamask',
+ *   accountLabel: 'Main DeFi',
+ *   connectionLabel: 'My MetaMask',
+ *   chainScope: [Chain.ETHEREUM, Chain.POLYGON]
+ * };
+ * ```
+ *
+ * @since 1.3.0
+ * @stability extended
+ *
+ * @see {@link ConnectedAccount} for the source account data
+ * @see {@link WatchAddress} for watch-only tracked addresses
+ */
+export interface TrackedAddress {
+    /** Account identifier */
+    accountId: AccountId;
+    /** Checksummed address */
+    address: string;
+    /** Wallet connection this address belongs to, or 'watch' */
+    walletConnectionId: WalletConnectionId | 'watch';
+    /** Wallet provider identifier, or 'watch' */
+    providerId: WalletProviderId | 'watch';
+    /** User-assigned account label */
+    accountLabel: string;
+    /** Label of the parent wallet connection */
+    connectionLabel: string;
+    /** Chain family of this tracked address, used for integration routing */
+    chainFamily: ChainFamily;
+    /** Chains to query for this address */
+    chainScope: Chain[];
+}

package/dist/interfaces/TrackedAddress.js

@@ -0,0 +1 @@
+export {};

package/dist/interfaces/Transaction.d.ts

@@ -1,5 +1,6 @@
 import { TransactionType } from '../enums/TransactionType';
 import { Chain } from '../enums/Chain';
+import { WalletConnectionId } from '../types/WalletConnectionId';
 import { Asset } from './Asset';
 import { Price } from './Price';
 import { Metadata } from './Metadata';
@@ -95,6 +96,8 @@ export interface Transaction {
     id: string;
     /** Reference to the Account.id where this transaction occurred */
     accountId: string;
+    /** Wallet connection this transaction belongs to, or 'watch' for watch addresses */
+    walletConnectionId?: WalletConnectionId | 'watch';
     /** Type of transaction operation */
     type: TransactionType;
     /** Transaction status for lifecycle tracking */

package/dist/interfaces/VaultPosition.d.ts

@@ -1,5 +1,6 @@
 import { Chain } from '../enums/Chain';
 import { VaultStrategyType } from '../enums/VaultStrategyType';
+import { DeFiDiscoverySource } from '../enums/DeFiDiscoverySource';
 import { Asset } from './Asset';
 import { Price } from './Price';
 import { Metadata } from './Metadata';
@@ -105,6 +106,8 @@ export interface VaultPosition {
     apy?: number;
     /** Current total value of the vault position */
     value?: Price;
+    /** How this position was discovered during portfolio scanning */
+    discoverySource?: DeFiDiscoverySource;
     /** Protocol-specific metadata (strategy details, harvest frequency, TVL, etc.) */
     metadata?: Metadata;
 }

package/dist/interfaces/WalletConnection.d.ts

@@ -0,0 +1,67 @@
+import { WalletConnectionId } from '../types/WalletConnectionId';
+import { WalletProviderId } from '../types/WalletProviderId';
+import { Chain } from '../enums/Chain';
+import { ChainFamily } from '../enums/ChainFamily';
+import { ConnectedAccount } from './ConnectedAccount';
+/**
+ * A connected wallet provider session.
+ *
+ * Represents a single connection session to a wallet provider. A user may have
+ * multiple connections to the same provider (e.g., two WalletConnect sessions)
+ * or connections to different providers simultaneously.
+ *
+ * Each connection maintains its own list of accumulated accounts discovered
+ * via EIP-1193 or manually added by the user.
+ *
+ * @example
+ * ```typescript
+ * import { WalletConnection } from '@cygnus-wealth/data-models';
+ *
+ * const connection: WalletConnection = {
+ *   connectionId: 'metamask:a1b2c3d4',
+ *   providerId: 'metamask',
+ *   providerName: 'MetaMask',
+ *   providerIcon: 'https://metamask.io/icon.svg',
+ *   connectionLabel: 'My MetaMask',
+ *   accounts: [],
+ *   activeAccountAddress: '0xAbCdEf1234567890',
+ *   supportedChains: [Chain.ETHEREUM, Chain.POLYGON],
+ *   connectedAt: '2026-01-15T10:30:00Z',
+ *   lastActiveAt: '2026-02-19T08:00:00Z',
+ *   sessionStatus: 'active'
+ * };
+ * ```
+ *
+ * @since 1.3.0
+ * @stability extended
+ *
+ * @see {@link ConnectedAccount} for individual account entries
+ * @see {@link WalletProviderId} for provider identification
+ * @see {@link WalletConnectionId} for connection identifier format
+ */
+export interface WalletConnection {
+    /** Unique connection identifier: `{providerId}:{randomId}` */
+    connectionId: WalletConnectionId;
+    /** Canonical wallet provider identifier */
+    providerId: WalletProviderId;
+    /** Human-readable provider name (e.g., "MetaMask") */
+    providerName: string;
+    /** URL or identifier for the provider's icon */
+    providerIcon: string;
+    /** User-assigned label (default: provider name) */
+    connectionLabel: string;
+    /** All accounts accumulated from this connection */
+    accounts: ConnectedAccount[];
+    /** Currently selected account address in the wallet provider, or null */
+    activeAccountAddress: string | null;
+    /** Chains this wallet connection supports */
+    supportedChains: Chain[];
+    /** Chain families this wallet connection supports (e.g., EVM, Solana, SUI) */
+    supportedChainFamilies: ChainFamily[];
+    /** ISO 8601 timestamp of initial connection */
+    connectedAt: string;
+    /** ISO 8601 timestamp of last activity */
+    lastActiveAt: string;
+    /** Session lifecycle status */
+    sessionStatus: 'active' | 'stale' | 'disconnected';
+}

package/dist/interfaces/WalletConnection.js

@@ -0,0 +1 @@
+export {};

package/dist/interfaces/WalletPortfolio.d.ts

@@ -0,0 +1,40 @@
+import { WalletConnectionId } from '../types/WalletConnectionId';
+import { AccountPortfolio } from './AccountPortfolio';
+import { Price } from './Price';
+/**
+ * Portfolio slice for all accounts in a wallet connection.
+ *
+ * Aggregates holdings across all accounts within a single wallet
+ * connection session.
+ *
+ * @example
+ * ```typescript
+ * import { WalletPortfolio } from '@cygnus-wealth/data-models';
+ *
+ * const walletPortfolio: WalletPortfolio = {
+ *   walletConnectionId: 'metamask:a1b2c3d4',
+ *   connectionLabel: 'My MetaMask',
+ *   providerName: 'MetaMask',
+ *   accounts: [],
+ *   totalValue: { value: 50000, currency: 'USD', timestamp: new Date() }
+ * };
+ * ```
+ *
+ * @since 1.3.0
+ * @stability extended
+ *
+ * @see {@link AccountPortfolio} for per-account breakdown
+ * @see {@link Portfolio} for aggregate portfolio
+ */
+export interface WalletPortfolio {
+    /** Wallet connection this portfolio belongs to */
+    walletConnectionId: WalletConnectionId;
+    /** User-assigned connection label */
+    connectionLabel: string;
+    /** Human-readable provider name */
+    providerName: string;
+    /** Per-account portfolio breakdowns within this wallet */
+    accounts: AccountPortfolio[];
+    /** Total value across all accounts in this wallet connection */
+    totalValue: Price;
+}

package/dist/interfaces/WalletPortfolio.js

@@ -0,0 +1 @@
+export {};

package/dist/interfaces/WatchAddress.d.ts

@@ -0,0 +1,42 @@
+import { AccountId } from '../types/AccountId';
+import { Chain } from '../enums/Chain';
+import { ChainFamily } from '../enums/ChainFamily';
+/**
+ * An address tracked independently of any wallet connection.
+ *
+ * Represents a read-only monitoring target that the user added manually
+ * without connecting a wallet. Watch addresses have no associated provider,
+ * no session lifecycle, and never receive `accountsChanged` events.
+ *
+ * @example
+ * ```typescript
+ * import { WatchAddress } from '@cygnus-wealth/data-models';
+ *
+ * const watched: WatchAddress = {
+ *   accountId: 'watch:0xAbCdEf1234567890',
+ *   address: '0xAbCdEf1234567890',
+ *   addressLabel: 'Vitalik.eth',
+ *   chainScope: [Chain.ETHEREUM],
+ *   addedAt: '2026-02-01T12:00:00Z'
+ * };
+ * ```
+ *
+ * @since 1.3.0
+ * @stability extended
+ *
+ * @see {@link AccountId} for identifier format (watch:\{checksummedAddress\})
+ */
+export interface WatchAddress {
+    /** Account identifier: `watch:{checksummedAddress}` */
+    accountId: AccountId;
+    /** Checksummed address being monitored */
+    address: string;
+    /** User-assigned label */
+    addressLabel: string;
+    /** Chain family of this watched address */
+    chainFamily: ChainFamily;
+    /** Chains to track this address on */
+    chainScope: Chain[];
+    /** ISO 8601 timestamp when this watch address was added */
+    addedAt: string;
+}

package/dist/interfaces/WatchAddress.js

@@ -0,0 +1 @@
+export {};

package/dist/types/AccountId.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Unique identifier for a specific account across the system.
+ *
+ * Format: `{walletConnectionId}:{chainFamily}:{address}` for connected accounts
+ * (e.g., `metamask:a1b2c3d4:evm:0xAbC...123`), or `watch:{address}`
+ * for watch addresses.
+ *
+ * The `chainFamily` segment (introduced in en-o8w) disambiguates addresses
+ * from the same wallet connection that span different chain families.
+ *
+ * This is the primary key used throughout the system to reference a specific
+ * account. It disambiguates the same address appearing in different wallet
+ * connections (e.g., imported into both MetaMask and Rabby).
+ *
+ * @example
+ * ```typescript
+ * import { AccountId } from '@cygnus-wealth/data-models';
+ *
+ * const evmAccountId: AccountId = 'metamask:a1b2c3d4:evm:0xAbCdEf1234567890';
+ * const solanaAccountId: AccountId = 'phantom:abc123:solana:7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU';
+ * const watchAccountId: AccountId = 'watch:0xAbCdEf1234567890';
+ * ```
+ *
+ * @since 1.3.0
+ * @stability extended
+ */
+export type AccountId = string;

package/dist/types/AccountId.js

@@ -0,0 +1 @@
+export {};

package/dist/types/Caip2ChainId.d.ts

@@ -0,0 +1,27 @@
+/**
+ * CAIP-2 chain identifier string type.
+ *
+ * Format: `{namespace}:{reference}` as defined by the Chain Agnostic
+ * Improvement Proposal 2. Used for WalletConnect v2 interoperability.
+ *
+ * Common namespace prefixes map to ChainFamily values:
+ * - `eip155` → ChainFamily.EVM (e.g., `eip155:1` for Ethereum mainnet)
+ * - `solana` → ChainFamily.SOLANA (e.g., `solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp`)
+ * - `bip122` → ChainFamily.BITCOIN
+ * - `cosmos` → ChainFamily.COSMOS
+ *
+ * @example
+ * ```typescript
+ * import { Caip2ChainId } from '@cygnus-wealth/data-models';
+ *
+ * const ethereumMainnet: Caip2ChainId = 'eip155:1';
+ * const polygon: Caip2ChainId = 'eip155:137';
+ * const solanaMainnet: Caip2ChainId = 'solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp';
+ * ```
+ *
+ * @since 1.5.0
+ * @stability extended
+ *
+ * @see {@link ChainFamily} for chain family classification
+ */
+export type Caip2ChainId = string;

package/dist/types/Caip2ChainId.js

@@ -0,0 +1 @@
+export {};

package/dist/types/WalletConnectionId.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Unique identifier for a specific wallet connection session.
+ *
+ * Format: `{providerId}:{randomId}` (e.g., `metamask:a1b2c3d4`).
+ * The randomId component ensures uniqueness when the same provider
+ * is connected multiple times (e.g., two WalletConnect sessions).
+ *
+ * @example
+ * ```typescript
+ * import { WalletConnectionId } from '@cygnus-wealth/data-models';
+ *
+ * const connectionId: WalletConnectionId = 'metamask:a1b2c3d4';
+ * const wcConnectionId: WalletConnectionId = 'walletconnect:x9y8z7w6';
+ * ```
+ *
+ * @since 1.3.0
+ * @stability extended
+ */
+export type WalletConnectionId = string;

package/dist/types/WalletConnectionId.js

@@ -0,0 +1 @@
+export {};

package/dist/types/WalletProviderId.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Canonical identifier for a wallet provider.
+ *
+ * String union type representing supported wallet providers. Extensible
+ * without breaking changes when new wallets are supported.
+ *
+ * @example
+ * ```typescript
+ * import { WalletProviderId } from '@cygnus-wealth/data-models';
+ *
+ * const provider: WalletProviderId = 'metamask';
+ * ```
+ *
+ * @since 1.3.0
+ * @stability extended
+ */
+export type WalletProviderId = 'metamask' | 'rabby' | 'walletconnect' | 'coinbase-wallet' | 'trust-wallet' | 'frame' | 'crypto-com-onchain' | 'phantom' | 'solflare' | 'backpack' | 'exodus' | 'manual';

package/dist/types/WalletProviderId.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cygnus-wealth/data-models",
-  "version": "1.2.0",
+  "version": "1.4.0",
   "description": "Shared TypeScript data models for CygnusWealth project",
   "main": "dist/cjs/index.js",
   "module": "dist/index.js",
@@ -21,6 +21,11 @@
       "import": "./dist/enums/Chain.js",
       "require": "./dist/cjs/enums/Chain.js"
     },
+    "./enums/ChainFamily": {
+      "types": "./dist/enums/ChainFamily.d.ts",
+      "import": "./dist/enums/ChainFamily.js",
+      "require": "./dist/cjs/enums/ChainFamily.js"
+    },
     "./enums/IntegrationSource": {
       "types": "./dist/enums/IntegrationSource.d.ts",
       "import": "./dist/enums/IntegrationSource.js",
@@ -41,6 +46,26 @@
       "import": "./dist/enums/LendingPositionType.js",
       "require": "./dist/cjs/enums/LendingPositionType.js"
     },
+    "./enums/VaultStrategyType": {
+      "types": "./dist/enums/VaultStrategyType.d.ts",
+      "import": "./dist/enums/VaultStrategyType.js",
+      "require": "./dist/cjs/enums/VaultStrategyType.js"
+    },
+    "./enums/DeFiPositionType": {
+      "types": "./dist/enums/DeFiPositionType.d.ts",
+      "import": "./dist/enums/DeFiPositionType.js",
+      "require": "./dist/cjs/enums/DeFiPositionType.js"
+    },
+    "./enums/DeFiProtocol": {
+      "types": "./dist/enums/DeFiProtocol.d.ts",
+      "import": "./dist/enums/DeFiProtocol.js",
+      "require": "./dist/cjs/enums/DeFiProtocol.js"
+    },
+    "./enums/DeFiDiscoverySource": {
+      "types": "./dist/enums/DeFiDiscoverySource.d.ts",
+      "import": "./dist/enums/DeFiDiscoverySource.js",
+      "require": "./dist/cjs/enums/DeFiDiscoverySource.js"
+    },
     "./interfaces/*": {
       "types": "./dist/interfaces/*.d.ts",
       "import": "./dist/interfaces/*.js",