@cygnus-wealth/data-models 1.1.2 → 1.2.0

package/dist/cjs/enums/VaultStrategyType.js

@@ -0,0 +1,34 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VaultStrategyType = void 0;
+/**
+ * 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
+ */
+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 || (exports.VaultStrategyType = VaultStrategyType = {}));

package/dist/cjs/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.LendingPositionType = exports.AccountType = exports.TransactionType = exports.IntegrationSource = exports.Chain = exports.AssetType = void 0;
+exports.VaultStrategyType = exports.LendingPositionType = exports.AccountType = exports.TransactionType = exports.IntegrationSource = exports.Chain = exports.AssetType = void 0;
 // Enums
 var AssetType_1 = require("./enums/AssetType");
 Object.defineProperty(exports, "AssetType", { enumerable: true, get: function () { return AssetType_1.AssetType; } });
@@ -14,3 +14,5 @@ var AccountType_1 = require("./enums/AccountType");
 Object.defineProperty(exports, "AccountType", { enumerable: true, get: function () { return AccountType_1.AccountType; } });
 var LendingPositionType_1 = require("./enums/LendingPositionType");
 Object.defineProperty(exports, "LendingPositionType", { enumerable: true, get: function () { return LendingPositionType_1.LendingPositionType; } });
+var VaultStrategyType_1 = require("./enums/VaultStrategyType");
+Object.defineProperty(exports, "VaultStrategyType", { enumerable: true, get: function () { return VaultStrategyType_1.VaultStrategyType; } });

package/dist/cjs/interfaces/VaultPosition.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

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

@@ -4,6 +4,7 @@ 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 { BaseEntity } from './interfaces/BaseEntity';
 export { Metadata } from './interfaces/Metadata';
 export { Asset } from './interfaces/Asset';
@@ -14,6 +15,7 @@ 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 { Account } from './interfaces/Account';
 export { Portfolio } from './interfaces/Portfolio';
 export { PortfolioAsset } from './interfaces/PortfolioAsset';

package/dist/index.js

@@ -5,3 +5,4 @@ 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';

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/VaultPosition.d.ts

@@ -0,0 +1,110 @@
+import { Chain } from '../enums/Chain';
+import { VaultStrategyType } from '../enums/VaultStrategyType';
+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;
+    /** Protocol-specific metadata (strategy details, harvest frequency, TVL, etc.) */
+    metadata?: Metadata;
+}

package/dist/interfaces/VaultPosition.js

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

package/package.json

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