@cygnus-wealth/data-models 1.1.2 → 1.4.0

package/dist/enums/DeFiProtocol.js

@@ -0,0 +1,43 @@
+/**
+ * Well-known DeFi protocol identifiers for position attribution.
+ *
+ * Provides standardized identifiers for major DeFi protocols across chains.
+ * Extensible via OTHER for protocols not yet explicitly enumerated.
+ * Protocol-specific version info (e.g., "Aave V3") should be stored in
+ * position metadata rather than the enum.
+ *
+ * @example
+ * ```typescript
+ * import { DeFiProtocol } from '@cygnus-wealth/data-models';
+ *
+ * const protocol = DeFiProtocol.AAVE;
+ * ```
+ *
+ * @since 1.3.0
+ * @stability extended
+ *
+ * @see {@link DeFiPosition} for usage in position interfaces
+ */
+export var DeFiProtocol;
+(function (DeFiProtocol) {
+    /** Beefy Finance — multi-chain yield optimizer / auto-compounder */
+    DeFiProtocol["BEEFY"] = "BEEFY";
+    /** Aave — decentralized lending and borrowing protocol */
+    DeFiProtocol["AAVE"] = "AAVE";
+    /** Uniswap — Ethereum-native AMM / DEX */
+    DeFiProtocol["UNISWAP"] = "UNISWAP";
+    /** Compound — algorithmic money market protocol */
+    DeFiProtocol["COMPOUND"] = "COMPOUND";
+    /** Lido — liquid staking for Ethereum and other PoS chains */
+    DeFiProtocol["LIDO"] = "LIDO";
+    /** Marinade Finance — liquid staking for Solana */
+    DeFiProtocol["MARINADE"] = "MARINADE";
+    /** Raydium — Solana AMM and liquidity provider */
+    DeFiProtocol["RAYDIUM"] = "RAYDIUM";
+    /** Jupiter — Solana DEX aggregator and perps platform */
+    DeFiProtocol["JUPITER"] = "JUPITER";
+    /** Orca — Solana concentrated liquidity DEX */
+    DeFiProtocol["ORCA"] = "ORCA";
+    /** Protocol not covered by other values; store name in metadata */
+    DeFiProtocol["OTHER"] = "OTHER";
+})(DeFiProtocol || (DeFiProtocol = {}));

package/dist/enums/IntegrationSource.d.ts

@@ -60,6 +60,14 @@ export declare enum IntegrationSource {
     MANUAL_ENTRY = "MANUAL_ENTRY",
     /** Data fetched directly from blockchain via RPC */
     BLOCKCHAIN_DIRECT = "BLOCKCHAIN_DIRECT",
+    /** SUI blockchain integration */
+    SUI = "SUI",
+    /** Bitcoin blockchain integration */
+    BITCOIN = "BITCOIN",
+    /** Cosmos ecosystem integration */
+    COSMOS = "COSMOS",
+    /** Aptos blockchain integration */
+    APTOS = "APTOS",
     /** Other or unclassified data source */
     OTHER = "OTHER"
 }

package/dist/enums/IntegrationSource.js

@@ -61,6 +61,14 @@ export var IntegrationSource;
     IntegrationSource["MANUAL_ENTRY"] = "MANUAL_ENTRY";
     /** Data fetched directly from blockchain via RPC */
     IntegrationSource["BLOCKCHAIN_DIRECT"] = "BLOCKCHAIN_DIRECT";
+    /** SUI blockchain integration */
+    IntegrationSource["SUI"] = "SUI";
+    /** Bitcoin blockchain integration */
+    IntegrationSource["BITCOIN"] = "BITCOIN";
+    /** Cosmos ecosystem integration */
+    IntegrationSource["COSMOS"] = "COSMOS";
+    /** Aptos blockchain integration */
+    IntegrationSource["APTOS"] = "APTOS";
     /** Other or unclassified data source */
     IntegrationSource["OTHER"] = "OTHER";
 })(IntegrationSource || (IntegrationSource = {}));

package/dist/enums/VaultStrategyType.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Strategy type for yield vault positions.
+ *
+ * Classifies the underlying strategy used by a yield vault to generate returns.
+ * Different strategy types carry different risk profiles and return characteristics.
+ *
+ * @example
+ * ```typescript
+ * import { VaultStrategyType } from '@cygnus-wealth/data-models';
+ *
+ * const strategyType = VaultStrategyType.YIELD_AGGREGATOR;
+ * ```
+ *
+ * @since 1.2.0
+ * @stability extended
+ *
+ * @see {@link VaultPosition} for usage in vault positions
+ */
+export declare enum VaultStrategyType {
+    /** Auto-compounding yield aggregator (e.g., Yearn, Beefy) */
+    YIELD_AGGREGATOR = "YIELD_AGGREGATOR",
+    /** Single-asset lending vault (e.g., Yearn USDC vault lending on Aave) */
+    LENDING = "LENDING",
+    /** Liquidity provision strategy (vault deposits into LP pools) */
+    LIQUIDITY_PROVISION = "LIQUIDITY_PROVISION",
+    /** Delta-neutral or options-based structured product */
+    STRUCTURED_PRODUCT = "STRUCTURED_PRODUCT",
+    /** Strategy type not covered by other categories */
+    OTHER = "OTHER"
+}

package/dist/enums/VaultStrategyType.js

@@ -0,0 +1,31 @@
+/**
+ * Strategy type for yield vault positions.
+ *
+ * Classifies the underlying strategy used by a yield vault to generate returns.
+ * Different strategy types carry different risk profiles and return characteristics.
+ *
+ * @example
+ * ```typescript
+ * import { VaultStrategyType } from '@cygnus-wealth/data-models';
+ *
+ * const strategyType = VaultStrategyType.YIELD_AGGREGATOR;
+ * ```
+ *
+ * @since 1.2.0
+ * @stability extended
+ *
+ * @see {@link VaultPosition} for usage in vault positions
+ */
+export var VaultStrategyType;
+(function (VaultStrategyType) {
+    /** Auto-compounding yield aggregator (e.g., Yearn, Beefy) */
+    VaultStrategyType["YIELD_AGGREGATOR"] = "YIELD_AGGREGATOR";
+    /** Single-asset lending vault (e.g., Yearn USDC vault lending on Aave) */
+    VaultStrategyType["LENDING"] = "LENDING";
+    /** Liquidity provision strategy (vault deposits into LP pools) */
+    VaultStrategyType["LIQUIDITY_PROVISION"] = "LIQUIDITY_PROVISION";
+    /** Delta-neutral or options-based structured product */
+    VaultStrategyType["STRUCTURED_PRODUCT"] = "STRUCTURED_PRODUCT";
+    /** Strategy type not covered by other categories */
+    VaultStrategyType["OTHER"] = "OTHER";
+})(VaultStrategyType || (VaultStrategyType = {}));

package/dist/index.d.ts

@@ -1,9 +1,14 @@
 export { AssetType } from './enums/AssetType';
 export { Chain } from './enums/Chain';
+export { ChainFamily } from './enums/ChainFamily';
 export { IntegrationSource } from './enums/IntegrationSource';
 export { TransactionType } from './enums/TransactionType';
 export { AccountType } from './enums/AccountType';
 export { LendingPositionType } from './enums/LendingPositionType';
+export { VaultStrategyType } from './enums/VaultStrategyType';
+export { DeFiPositionType } from './enums/DeFiPositionType';
+export { DeFiProtocol } from './enums/DeFiProtocol';
+export { DeFiDiscoverySource } from './enums/DeFiDiscoverySource';
 export { BaseEntity } from './interfaces/BaseEntity';
 export { Metadata } from './interfaces/Metadata';
 export { Asset } from './interfaces/Asset';
@@ -14,9 +19,29 @@ export { Balance } from './interfaces/Balance';
 export { LiquidityPosition } from './interfaces/LiquidityPosition';
 export { StakedPosition } from './interfaces/StakedPosition';
 export { LendingPosition } from './interfaces/LendingPosition';
+export { VaultPosition } from './interfaces/VaultPosition';
+export { DeFiPosition } from './interfaces/DeFiPosition';
 export { Account } from './interfaces/Account';
 export { Portfolio } from './interfaces/Portfolio';
 export { PortfolioAsset } from './interfaces/PortfolioAsset';
+export type { WalletProviderId } from './types/WalletProviderId';
+export type { WalletConnectionId } from './types/WalletConnectionId';
+export type { AccountId } from './types/AccountId';
+export type { Caip2ChainId } from './types/Caip2ChainId';
+export type { WalletConnection } from './interfaces/WalletConnection';
+export type { ConnectedAccount } from './interfaces/ConnectedAccount';
+export type { WatchAddress } from './interfaces/WatchAddress';
+export type { AccountGroup } from './interfaces/AccountGroup';
+export type { AccountPortfolio } from './interfaces/AccountPortfolio';
+export type { WalletPortfolio } from './interfaces/WalletPortfolio';
+export type { GroupPortfolio } from './interfaces/GroupPortfolio';
+export type { AccountSummary } from './interfaces/AccountSummary';
+export type { AssetDistribution } from './interfaces/AssetDistribution';
+export type { AccountAssetEntry } from './interfaces/AccountAssetEntry';
+export type { TrackedAddress } from './interfaces/TrackedAddress';
+export type { AccountMetadata } from './interfaces/AccountMetadata';
+export type { AddressRequest } from './interfaces/AddressRequest';
+export type { AccountBalanceList, AccountBalance, AccountError } from './interfaces/AccountBalanceList';
 export { Transaction } from './interfaces/Transaction';
 export { IntegrationCredentials } from './interfaces/IntegrationCredentials';
 export { SyncStatus } from './interfaces/SyncStatus';

package/dist/index.js

@@ -1,7 +1,12 @@
 // Enums
 export { AssetType } from './enums/AssetType';
 export { Chain } from './enums/Chain';
+export { ChainFamily } from './enums/ChainFamily';
 export { IntegrationSource } from './enums/IntegrationSource';
 export { TransactionType } from './enums/TransactionType';
 export { AccountType } from './enums/AccountType';
 export { LendingPositionType } from './enums/LendingPositionType';
+export { VaultStrategyType } from './enums/VaultStrategyType';
+export { DeFiPositionType } from './enums/DeFiPositionType';
+export { DeFiProtocol } from './enums/DeFiProtocol';
+export { DeFiDiscoverySource } from './enums/DeFiDiscoverySource';

package/dist/interfaces/Account.d.ts

@@ -4,6 +4,7 @@ import { Balance } from './Balance';
 import { LiquidityPosition } from './LiquidityPosition';
 import { StakedPosition } from './StakedPosition';
 import { LendingPosition } from './LendingPosition';
+import { VaultPosition } from './VaultPosition';
 import { NFT } from './NFT';
 import { Price } from './Price';
 import { Metadata } from './Metadata';
@@ -105,6 +106,8 @@ export interface Account {
     stakedPositions?: StakedPosition[];
     /** Array of lending/borrowing positions (for DeFi money markets) */
     lendingPositions?: LendingPosition[];
+    /** Array of yield vault positions (for vault deposits) */
+    vaultPositions?: VaultPosition[];
     /** Array of NFTs held in this account */
     nfts?: NFT[];
     /** Total value of all holdings in this account (sum of all positions) */

package/dist/interfaces/AccountAssetEntry.d.ts

@@ -0,0 +1,42 @@
+import { AccountId } from '../types/AccountId';
+import { Balance } from './Balance';
+import { Price } from './Price';
+/**
+ * A single account's holding of an asset within an asset distribution.
+ *
+ * Used as part of {@link AssetDistribution} to show how much of a specific
+ * asset is held in each account and what percentage of the total it represents.
+ *
+ * @example
+ * ```typescript
+ * import { AccountAssetEntry } from '@cygnus-wealth/data-models';
+ *
+ * const entry: AccountAssetEntry = {
+ *   accountId: 'metamask:a1b2:0xAbc',
+ *   accountLabel: 'Main DeFi',
+ *   connectionLabel: 'My MetaMask',
+ *   quantity: { assetId: 'eth', asset: ethAsset, amount: '7.0' },
+ *   value: { value: 14000, currency: 'USD', timestamp: new Date() },
+ *   percentage: 66.67
+ * };
+ * ```
+ *
+ * @since 1.3.0
+ * @stability extended
+ *
+ * @see {@link AssetDistribution} for the parent distribution context
+ */
+export interface AccountAssetEntry {
+    /** Account holding this portion of the asset */
+    accountId: AccountId;
+    /** User-assigned account label */
+    accountLabel: string;
+    /** Label of the parent wallet connection */
+    connectionLabel: string;
+    /** Quantity of the asset in this account */
+    quantity: Balance;
+    /** Value of this account's holding */
+    value: Price;
+    /** Percentage of total for this asset (e.g., 66.67 = 66.67%) */
+    percentage: number;
+}

package/dist/interfaces/AccountAssetEntry.js

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

package/dist/interfaces/AccountBalanceList.d.ts

@@ -0,0 +1,85 @@
+import { AccountId } from '../types/AccountId';
+import { Chain } from '../enums/Chain';
+import { Balance } from './Balance';
+/**
+ * A single account's balance result for a specific chain.
+ *
+ * Contains the native balance and token balances for one account
+ * on one chain, with the AccountId for attribution.
+ *
+ * @since 1.3.0
+ * @stability extended
+ *
+ * @see {@link AccountBalanceList} for the container type
+ */
+export interface AccountBalance {
+    /** Account this balance belongs to */
+    accountId: AccountId;
+    /** Checksummed address */
+    address: string;
+    /** Chain this balance was fetched from */
+    chainId: Chain;
+    /** Native token balance (e.g., ETH on Ethereum) */
+    nativeBalance: Balance;
+    /** ERC-20 and other token balances */
+    tokenBalances: Balance[];
+}
+/**
+ * Error encountered while fetching data for a specific account.
+ *
+ * Supports partial failure: some accounts may succeed while others fail.
+ *
+ * @since 1.3.0
+ * @stability extended
+ */
+export interface AccountError {
+    /** Account that encountered the error */
+    accountId: AccountId;
+    /** Chain where the error occurred */
+    chainId: Chain;
+    /** Error message */
+    message: string;
+    /** Error code for programmatic handling */
+    code?: string;
+}
+/**
+ * Account-attributed balance results with support for partial failure.
+ *
+ * Returned by integration contracts when fetching balances for multiple
+ * accounts. Each balance carries its AccountId for attribution, and
+ * per-account errors are reported separately.
+ *
+ * @example
+ * ```typescript
+ * import { AccountBalanceList } from '@cygnus-wealth/data-models';
+ *
+ * const result: AccountBalanceList = {
+ *   balances: [
+ *     {
+ *       accountId: 'metamask:a1b2:0xAbc',
+ *       address: '0xAbc',
+ *       chainId: Chain.ETHEREUM,
+ *       nativeBalance: ethBalance,
+ *       tokenBalances: [usdcBalance, daiBalance]
+ *     }
+ *   ],
+ *   errors: [],
+ *   timestamp: '2026-02-19T08:00:00Z'
+ * };
+ * ```
+ *
+ * @since 1.3.0
+ * @stability extended
+ *
+ * @see {@link AddressRequest} for the request format
+ * @see {@link AccountBalance} for individual balance results
+ * @see {@link AccountError} for per-account errors
+ */
+export interface AccountBalanceList {
+    /** Successful balance results */
+    balances: AccountBalance[];
+    /** Per-account errors (partial failure) */
+    errors: AccountError[];
+    /** ISO 8601 timestamp of the fetch */
+    timestamp: string;
+}

package/dist/interfaces/AccountBalanceList.js

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

package/dist/interfaces/AccountGroup.d.ts

@@ -0,0 +1,37 @@
+import { AccountId } from '../types/AccountId';
+/**
+ * User-defined grouping of accounts for organizational purposes.
+ *
+ * Allows users to create custom groups like "DeFi Accounts", "Long-term Holdings",
+ * or "Family" that span across wallet connections and watch addresses.
+ *
+ * @example
+ * ```typescript
+ * import { AccountGroup } from '@cygnus-wealth/data-models';
+ *
+ * const group: AccountGroup = {
+ *   groupId: 'group-defi-1',
+ *   groupName: 'DeFi Accounts',
+ *   accountIds: [
+ *     'metamask:a1b2c3d4:0xAbC...123',
+ *     'rabby:e5f6g7h8:0xDef...456'
+ *   ],
+ *   createdAt: '2026-02-10T09:00:00Z'
+ * };
+ * ```
+ *
+ * @since 1.3.0
+ * @stability extended
+ *
+ * @see {@link AccountId} for account identifier format
+ */
+export interface AccountGroup {
+    /** Unique group identifier */
+    groupId: string;
+    /** User-assigned group name */
+    groupName: string;
+    /** References to accounts from any connection or watch addresses */
+    accountIds: AccountId[];
+    /** ISO 8601 timestamp when the group was created */
+    createdAt: string;
+}

package/dist/interfaces/AccountGroup.js

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

package/dist/interfaces/AccountMetadata.d.ts

@@ -0,0 +1,54 @@
+import { AccountId } from '../types/AccountId';
+import { WalletConnectionId } from '../types/WalletConnectionId';
+import { WalletProviderId } from '../types/WalletProviderId';
+/**
+ * Full metadata for an account, including group membership and lifecycle status.
+ *
+ * Provides comprehensive account context for portfolio aggregation and UI
+ * display, combining identity, labeling, and status information.
+ *
+ * @example
+ * ```typescript
+ * import { AccountMetadata } from '@cygnus-wealth/data-models';
+ *
+ * const metadata: AccountMetadata = {
+ *   accountId: 'metamask:a1b2c3d4:0xAbCdEf1234567890',
+ *   address: '0xAbCdEf1234567890',
+ *   accountLabel: 'Main DeFi',
+ *   connectionLabel: 'My MetaMask',
+ *   providerId: 'metamask',
+ *   walletConnectionId: 'metamask:a1b2c3d4',
+ *   groups: ['group-defi-1'],
+ *   discoveredAt: '2026-01-15T10:30:00Z',
+ *   isStale: false,
+ *   isActive: true
+ * };
+ * ```
+ *
+ * @since 1.3.0
+ * @stability extended
+ *
+ * @see {@link TrackedAddress} for the lightweight address tracking variant
+ */
+export interface AccountMetadata {
+    /** Account identifier */
+    accountId: AccountId;
+    /** Checksummed address */
+    address: string;
+    /** User-assigned account label */
+    accountLabel: string;
+    /** Label of the parent wallet connection */
+    connectionLabel: string;
+    /** Wallet provider identifier, or 'watch' for watch addresses */
+    providerId: WalletProviderId | 'watch';
+    /** Wallet connection identifier, or 'watch' for watch addresses */
+    walletConnectionId: WalletConnectionId | 'watch';
+    /** Group IDs this account belongs to */
+    groups: string[];
+    /** ISO 8601 timestamp when first discovered */
+    discoveredAt: string;
+    /** Whether the provider no longer exposes this account */
+    isStale: boolean;
+    /** Whether this is the currently active account in the provider */
+    isActive: boolean;
+}

package/dist/interfaces/AccountMetadata.js

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

package/dist/interfaces/AccountPortfolio.d.ts

@@ -0,0 +1,47 @@
+import { AccountId } from '../types/AccountId';
+import { WalletConnectionId } from '../types/WalletConnectionId';
+import { Asset } from './Asset';
+import { Price } from './Price';
+/**
+ * Portfolio slice for a single account.
+ *
+ * Represents the holdings attributed to one specific account, whether
+ * it's a connected wallet account or a watch address.
+ *
+ * @example
+ * ```typescript
+ * import { AccountPortfolio } from '@cygnus-wealth/data-models';
+ *
+ * const accountPortfolio: AccountPortfolio = {
+ *   accountId: 'metamask:a1b2c3d4:0xAbCdEf1234567890',
+ *   accountLabel: 'Main DeFi',
+ *   walletConnectionId: 'metamask:a1b2c3d4',
+ *   providerName: 'MetaMask',
+ *   assets: [],
+ *   totalValue: { value: 25000, currency: 'USD', timestamp: new Date() },
+ *   lastUpdated: '2026-02-19T08:00:00Z'
+ * };
+ * ```
+ *
+ * @since 1.3.0
+ * @stability extended
+ *
+ * @see {@link WalletPortfolio} for per-wallet rollup
+ * @see {@link Portfolio} for aggregate portfolio
+ */
+export interface AccountPortfolio {
+    /** Account this portfolio slice belongs to */
+    accountId: AccountId;
+    /** User-assigned account label */
+    accountLabel: string;
+    /** Wallet connection this account belongs to, or 'watch' for watch addresses */
+    walletConnectionId: WalletConnectionId | 'watch';
+    /** Human-readable provider name */
+    providerName: string;
+    /** Assets held in this account */
+    assets: Asset[];
+    /** Total value of this account's holdings */
+    totalValue: Price;
+    /** ISO 8601 timestamp of last data update */
+    lastUpdated: string;
+}

package/dist/interfaces/AccountPortfolio.js

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

package/dist/interfaces/AccountSummary.d.ts

@@ -0,0 +1,49 @@
+import { AccountId } from '../types/AccountId';
+import { WalletProviderId } from '../types/WalletProviderId';
+import { Chain } from '../enums/Chain';
+import { Price } from './Price';
+/**
+ * Summary view of an account for cross-account analysis.
+ *
+ * Lightweight representation containing key metrics for each account,
+ * suitable for dashboard summary views and account comparison.
+ *
+ * @example
+ * ```typescript
+ * import { AccountSummary } from '@cygnus-wealth/data-models';
+ *
+ * const summary: AccountSummary = {
+ *   accountId: 'metamask:a1b2c3d4:0xAbCdEf1234567890',
+ *   accountLabel: 'Main DeFi',
+ *   connectionLabel: 'My MetaMask',
+ *   providerId: 'metamask',
+ *   totalValue: { value: 25000, currency: 'USD', timestamp: new Date() },
+ *   assetCount: 12,
+ *   chains: [Chain.ETHEREUM, Chain.POLYGON],
+ *   lastUpdated: '2026-02-19T08:00:00Z'
+ * };
+ * ```
+ *
+ * @since 1.3.0
+ * @stability extended
+ *
+ * @see {@link AccountPortfolio} for full account portfolio details
+ */
+export interface AccountSummary {
+    /** Account identifier */
+    accountId: AccountId;
+    /** User-assigned account label */
+    accountLabel: string;
+    /** Label of the parent wallet connection */
+    connectionLabel: string;
+    /** Wallet provider identifier, or 'watch' for watch addresses */
+    providerId: WalletProviderId | 'watch';
+    /** Total value of the account's holdings */
+    totalValue: Price;
+    /** Number of distinct assets held */
+    assetCount: number;
+    /** Chains this account has activity on */
+    chains: Chain[];
+    /** ISO 8601 timestamp of last data update */
+    lastUpdated: string;
+}

package/dist/interfaces/AccountSummary.js

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

package/dist/interfaces/AddressRequest.d.ts

@@ -0,0 +1,36 @@
+import { AccountId } from '../types/AccountId';
+import { Chain } from '../enums/Chain';
+import { ChainFamily } from '../enums/ChainFamily';
+/**
+ * Request to query data for a specific account address.
+ *
+ * Used by integration contracts to request data with account attribution.
+ * Carries the AccountId so results can be attributed back to the originating
+ * account, and includes chain scope for per-account chain filtering.
+ *
+ * @example
+ * ```typescript
+ * import { AddressRequest, Chain } from '@cygnus-wealth/data-models';
+ *
+ * const request: AddressRequest = {
+ *   accountId: 'metamask:a1b2c3d4:0xAbCdEf1234567890',
+ *   address: '0xAbCdEf1234567890',
+ *   chainScope: [Chain.ETHEREUM, Chain.POLYGON, Chain.ARBITRUM]
+ * };
+ * ```
+ *
+ * @since 1.3.0
+ * @stability extended
+ *
+ * @see {@link AccountBalanceList} for the response format
+ */
+export interface AddressRequest {
+    /** Account identifier for result attribution */
+    accountId: AccountId;
+    /** Checksummed address to query */
+    address: string;
+    /** Chain family for routing to the correct integration */
+    chainFamily: ChainFamily;
+    /** Chains to query for this address */
+    chainScope: Chain[];
+}

package/dist/interfaces/AddressRequest.js

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

package/dist/interfaces/Asset.d.ts

@@ -1,5 +1,7 @@
 import { AssetType } from '../enums/AssetType';
 import { Chain } from '../enums/Chain';
+import { AccountId } from '../types/AccountId';
+import { WalletConnectionId } from '../types/WalletConnectionId';
 import { Metadata } from './Metadata';
 /**
  * Universal asset representation normalizing data from multiple sources.
@@ -72,6 +74,10 @@ export interface Asset {
     cusip?: string;
     /** ISIN identifier for international securities */
     isin?: string;
+    /** Account holding this asset (for multi-wallet multi-account attribution) */
+    accountId?: AccountId;
+    /** Wallet connection this asset belongs to, or 'watch' for watch addresses */
+    walletConnectionId?: WalletConnectionId | 'watch';
     /** Source-specific additional data and custom fields */
     metadata?: Metadata;
 }

package/dist/interfaces/AssetDistribution.d.ts

@@ -0,0 +1,45 @@
+import { Balance } from './Balance';
+import { Price } from './Price';
+import { AccountAssetEntry } from './AccountAssetEntry';
+/**
+ * Distribution of a specific asset across multiple accounts.
+ *
+ * Shows how holdings of a single asset (by symbol) are distributed
+ * across the user's accounts, useful for concentration analysis.
+ *
+ * @example
+ * ```typescript
+ * import { AssetDistribution } from '@cygnus-wealth/data-models';
+ *
+ * const ethDistribution: AssetDistribution = {
+ *   symbol: 'ETH',
+ *   totalQuantity: { assetId: 'eth', asset: ethAsset, amount: '10.5' },
+ *   totalValue: { value: 21000, currency: 'USD', timestamp: new Date() },
+ *   distribution: [
+ *     {
+ *       accountId: 'metamask:a1b2:0xAbc',
+ *       accountLabel: 'Main',
+ *       connectionLabel: 'MetaMask',
+ *       quantity: { assetId: 'eth', asset: ethAsset, amount: '7.0' },
+ *       value: { value: 14000, currency: 'USD', timestamp: new Date() },
+ *       percentage: 66.67
+ *     }
+ *   ]
+ * };
+ * ```
+ *
+ * @since 1.3.0
+ * @stability extended
+ *
+ * @see {@link AccountAssetEntry} for per-account breakdown
+ */
+export interface AssetDistribution {
+    /** Asset trading symbol */
+    symbol: string;
+    /** Total quantity across all accounts */
+    totalQuantity: Balance;
+    /** Total value across all accounts */
+    totalValue: Price;
+    /** Per-account breakdown of this asset's distribution */
+    distribution: AccountAssetEntry[];
+}

package/dist/interfaces/AssetDistribution.js

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