@cygnus-wealth/data-models 1.1.2 → 1.4.0

package/dist/interfaces/ConnectedAccount.d.ts

@@ -0,0 +1,52 @@
+import { AccountId } from '../types/AccountId';
+import { Chain } from '../enums/Chain';
+import { ChainFamily } from '../enums/ChainFamily';
+/**
+ * A single account within a wallet connection.
+ *
+ * Represents an address discovered via a wallet provider (EIP-1193) or
+ * manually added to a connection's account list. Tracks discovery time,
+ * staleness, and active status relative to the wallet provider.
+ *
+ * @example
+ * ```typescript
+ * import { ConnectedAccount } from '@cygnus-wealth/data-models';
+ *
+ * const account: ConnectedAccount = {
+ *   accountId: 'metamask:a1b2c3d4:0xAbCdEf1234567890',
+ *   address: '0xAbCdEf1234567890',
+ *   accountLabel: 'Main DeFi',
+ *   chainScope: [Chain.ETHEREUM, Chain.POLYGON],
+ *   source: 'provider',
+ *   discoveredAt: '2026-01-15T10:30:00Z',
+ *   isStale: false,
+ *   isActive: true
+ * };
+ * ```
+ *
+ * @since 1.3.0
+ * @stability extended
+ *
+ * @see {@link WalletConnection} for the parent connection
+ * @see {@link AccountId} for identifier format
+ */
+export interface ConnectedAccount {
+    /** Unique account identifier: `{walletConnectionId}:{checksummedAddress}` */
+    accountId: AccountId;
+    /** Checksummed EVM address */
+    address: string;
+    /** User-assigned label (default: truncated address) */
+    accountLabel: string;
+    /** Chain family this account belongs to */
+    chainFamily: ChainFamily;
+    /** Chains to track this account on (default: all supported by the connection) */
+    chainScope: Chain[];
+    /** How this account was added: 'provider' = discovered via EIP-1193; 'manual' = user typed the address */
+    source: 'provider' | 'manual';
+    /** ISO 8601 timestamp when first seen */
+    discoveredAt: string;
+    /** True if the provider no longer includes this account in eth_requestAccounts responses */
+    isStale: boolean;
+    /** True if this is the currently selected account in the wallet provider */
+    isActive: boolean;
+}

package/dist/interfaces/ConnectedAccount.js

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

package/dist/interfaces/DeFiPosition.d.ts

@@ -0,0 +1,79 @@
+import { Chain } from '../enums/Chain';
+import { DeFiPositionType } from '../enums/DeFiPositionType';
+import { DeFiProtocol } from '../enums/DeFiProtocol';
+import { DeFiDiscoverySource } from '../enums/DeFiDiscoverySource';
+import { AccountId } from '../types/AccountId';
+import { Balance } from './Balance';
+import { Price } from './Price';
+import { Metadata } from './Metadata';
+/**
+ * Base interface for all DeFi positions across protocols and chains.
+ *
+ * Provides a unified shape for any DeFi position — vaults, lending, liquidity
+ * pools, staking, farming, and perp positions. Concrete subtypes
+ * ({@link VaultPosition}, {@link LendingPosition}, {@link LiquidityPosition},
+ * {@link StakedPosition}) add protocol-specific fields.
+ *
+ * **Discovery Paths:**
+ * - `WALLET_TOKEN_SCAN` — position inferred from receipt tokens in wallet
+ * - `CONTRACT_QUERY` — position read from protocol contract state
+ *
+ * @example
+ * ```typescript
+ * import {
+ *   DeFiPosition,
+ *   DeFiPositionType,
+ *   DeFiProtocol,
+ *   DeFiDiscoverySource,
+ *   Chain
+ * } from '@cygnus-wealth/data-models';
+ *
+ * const position: DeFiPosition = {
+ *   id: 'aave-supply-usdc-1',
+ *   type: DeFiPositionType.LENDING_SUPPLY,
+ *   protocol: DeFiProtocol.AAVE,
+ *   chain: Chain.ETHEREUM,
+ *   underlyingAssets: [{
+ *     assetId: 'ethereum-usdc',
+ *     asset: { id: 'ethereum-usdc', symbol: 'USDC', name: 'USD Coin', type: 'CRYPTOCURRENCY', decimals: 6 },
+ *     amount: '50000'
+ *   }],
+ *   value: { value: 50125.50, currency: 'USD', timestamp: new Date() },
+ *   apy: 3.5,
+ *   rewards: [],
+ *   discoverySource: DeFiDiscoverySource.CONTRACT_QUERY
+ * };
+ * ```
+ *
+ * @since 1.3.0
+ * @stability extended
+ *
+ * @see {@link VaultPosition} for vault-specific fields
+ * @see {@link LendingPosition} for lending-specific fields
+ * @see {@link LiquidityPosition} for LP-specific fields
+ * @see {@link StakedPosition} for staking-specific fields
+ */
+export interface DeFiPosition {
+    /** Unique identifier for this position */
+    id: string;
+    /** Classification of the DeFi position */
+    type: DeFiPositionType;
+    /** Protocol where the position exists */
+    protocol: DeFiProtocol;
+    /** Blockchain network where the position exists */
+    chain: Chain;
+    /** Underlying assets in this position (tokens deposited, staked, or provided) */
+    underlyingAssets: Balance[];
+    /** Current total value of the position */
+    value?: Price;
+    /** Annual Percentage Yield or Rate (e.g., 8.5 = 8.5%) */
+    apy?: number;
+    /** Earned rewards (claimable or accrued incentive tokens) */
+    rewards: Balance[];
+    /** How this position was discovered during portfolio scanning */
+    discoverySource?: DeFiDiscoverySource;
+    /** Account identifier for multi-wallet attribution (alongside ownerAddress) */
+    accountId?: AccountId;
+    /** Protocol-specific metadata (version, contract addresses, TVL, etc.) */
+    metadata?: Metadata;
+}

package/dist/interfaces/DeFiPosition.js

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

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

@@ -0,0 +1,113 @@
+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';
+/**
+ * Yield vault deposit position tracking shares and performance.
+ *
+ * Represents user deposits in yield-generating vaults (Yearn, Beefy, Harvest,
+ * Sommelier, etc.) where assets are deposited into a vault contract that
+ * executes automated strategies. Tracks deposited amount, vault share tokens,
+ * APY, and underlying asset.
+ *
+ * **Design Pattern:** DeFi position entity for vault operations. Vaults issue
+ * share tokens representing proportional ownership. The share price (pricePerShare)
+ * increases over time as the vault earns yield, meaning the same number of shares
+ * becomes redeemable for more underlying tokens.
+ *
+ * @example
+ * ```typescript
+ * import { VaultPosition, VaultStrategyType, Chain, AssetType } from '@cygnus-wealth/data-models';
+ *
+ * // Yearn USDC vault deposit
+ * const yearnPosition: VaultPosition = {
+ *   id: 'yearn-usdc-vault-123',
+ *   protocol: 'Yearn V3',
+ *   vaultAddress: '0xa354F35829Ae975e850e23e9615b11Da1B3dC4DE',
+ *   vaultName: 'USDC yVault',
+ *   chain: Chain.ETHEREUM,
+ *   strategyType: VaultStrategyType.YIELD_AGGREGATOR,
+ *   depositAsset: {
+ *     id: 'ethereum-usdc',
+ *     symbol: 'USDC',
+ *     name: 'USD Coin',
+ *     type: AssetType.CRYPTOCURRENCY,
+ *     decimals: 6
+ *   },
+ *   depositedAmount: '50000.000000',
+ *   shareBalance: '48500.000000',
+ *   pricePerShare: 1.0309,
+ *   apy: 8.5,
+ *   value: {
+ *     value: 50000,
+ *     currency: 'USD',
+ *     timestamp: new Date()
+ *   }
+ * };
+ *
+ * // Beefy auto-compounder on Arbitrum
+ * const beefyPosition: VaultPosition = {
+ *   id: 'beefy-arb-eth-usdc-456',
+ *   protocol: 'Beefy',
+ *   vaultAddress: '0xDeadBeef...',
+ *   vaultName: 'mooArbETH-USDC',
+ *   chain: Chain.ARBITRUM,
+ *   strategyType: VaultStrategyType.LIQUIDITY_PROVISION,
+ *   depositAsset: {
+ *     id: 'arbitrum-eth',
+ *     symbol: 'ETH',
+ *     name: 'Ethereum',
+ *     type: AssetType.CRYPTOCURRENCY,
+ *     decimals: 18
+ *   },
+ *   depositedAmount: '2.5',
+ *   shareBalance: '2.35',
+ *   pricePerShare: 1.0638,
+ *   apy: 12.3,
+ *   value: {
+ *     value: 5000,
+ *     currency: 'USD',
+ *     timestamp: new Date()
+ *   }
+ * };
+ * ```
+ *
+ * @since 1.2.0
+ * @stability extended
+ *
+ * @see {@link VaultStrategyType} for vault strategy classification
+ * @see {@link Asset} for deposit asset definition
+ * @see {@link Account} for position aggregation
+ */
+export interface VaultPosition {
+    /** Unique identifier for this vault position */
+    id: string;
+    /** Vault protocol name (e.g., 'Yearn V3', 'Beefy', 'Harvest', 'Sommelier') */
+    protocol: string;
+    /** Smart contract address of the vault */
+    vaultAddress: string;
+    /** Human-readable vault name (e.g., 'USDC yVault', 'mooArbETH-USDC') */
+    vaultName: string;
+    /** Blockchain network where the vault exists */
+    chain: Chain;
+    /** Classification of the vault's underlying strategy */
+    strategyType: VaultStrategyType;
+    /** Asset deposited into the vault (the underlying token) */
+    depositAsset: Asset;
+    /** Amount of underlying asset deposited (as string for precision) */
+    depositedAmount: string;
+    /** Amount of vault share tokens held (as string for precision) */
+    shareBalance?: string;
+    /** Current price per share in terms of deposit asset (e.g., 1.03 means 3% profit) */
+    pricePerShare?: number;
+    /** Annual Percentage Yield for the vault (e.g., 8.5 = 8.5%) */
+    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/VaultPosition.js

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

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