@eulerxyz/euler-v2-sdk 0.1.0-beta

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Euler
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,115 @@
+# Euler V2 SDK
+
+# NOTE this is a beta version, proceed with caution.
+
+## Installation
+
+```bash
+npm install euler-v2-sdk
+```
+
+## Example Usage (Multiply + Simulation)
+
+```typescript
+import { buildEulerSDK, getSubAccountAddress } from "euler-v2-sdk";
+import { mainnet } from "viem/chains";
+import { parseUnits } from "viem";
+
+const sdk = await buildEulerSDK({
+  rpcUrls: {
+    [mainnet.id]: "https://your-rpc-url",
+  },
+});
+
+const owner = "0xYourEOA";
+const subAccount = getSubAccountAddress(owner, 1);
+
+const account = await sdk.accountService.fetchAccount(mainnet.id, owner, {
+  populateVaults: false,
+});
+
+const quotes = await sdk.swapService.getDepositQuote({
+  chainId: mainnet.id,
+  fromVault: "0xLiabilityVault",
+  toVault: "0xLongVault",
+  fromAccount: subAccount,
+  toAccount: subAccount,
+  fromAsset: "0xLiabilityAsset",
+  toAsset: "0xLongAsset",
+  amount: parseUnits("50", 6),
+  origin: owner,
+  slippage: 0.5,
+  deadline: Math.floor(Date.now() / 1000) + 1800,
+});
+
+const plan = sdk.executionService.planMultiplyWithSwap({
+  account,
+  collateralVault: "0xCollateralVault",
+  collateralAmount: parseUnits("100", 6),
+  collateralAsset: "0xCollateralAsset",
+  swapQuote: quotes[0]!,
+});
+
+const simulation = await sdk.simulationService.simulateTransactionPlan(
+  mainnet.id,
+  owner,
+  plan,
+  { stateOverrides: true }
+);
+
+// Use simulated account and vaults state in the UI.
+// Use simulation.canExecute or errors to decide whether and how to execute this plan in your app.
+```
+
+## What This SDK Is For
+
+`euler-v2-sdk` provides everything needed to interact with Euler V2 lending contracts:
+
+- fetching account, vault, wallet, and market data
+- planning and composing EVC transaction batches
+- resolving approvals (approve/Permit2 paths)
+- simulating transactions before execution
+- handling swaps, pricing, rewards, labels, and deployed addresses
+- fetching oracle adapter metadata/checks (provider, methodology, checks)
+
+The SDK is built with dependency injection, so you can use `buildEulerSDK()` for a default setup, run individual services in isolation, or modify the behavior with your custom implementations.
+
+## Configuration
+
+Only `rpcUrls` is required. All other options (pricing backend, swap API, rewards, subgraphs, plugins, etc.) have sensible defaults or are optional. See the full [Configuration Reference](./docs/configuration.md) for all options and defaults.
+
+## Docs Table of Contents
+
+All docs are in [`./docs`](./docs).
+
+1. [Configuration](./docs/configuration.md) - All `buildEulerSDK()` options, defaults, and service overrides.
+2. [Basic Usage](./docs/basic-usage.md) - Fast setup and common account/vault usage patterns.
+3. [SDK Architecture Overview](./docs/sdk-architecture-overview.md) - High-level architecture, dependency injection model, and composition options.
+4. [Services](./docs/services.md) - Service map, top-level entry points, and lower-level support services.
+5. [Execution Service](./docs/execution-service.md) - `encodeX` vs `planX`, approvals flow, `mergePlans`, and `describeBatch`.
+6. [Simulations and State Overrides](./docs/simulations-and-state-overrides.md) - Plan simulation flow, validation output, and state override utilities.
+7. [Swaps](./docs/swaps.md) - Swap quote APIs and how swap payloads fit into plans.
+8. [Pricing System](./docs/pricing-system.md) - Price data pipeline, fallback behavior, and pricing integration points.
+9. [Data Architecture](./docs/data-architecture.md) - Entities/adapters/services layering, population model, and data flow.
+10. [Cross-Service Data Population](./docs/cross-service-data-population.md) - How services enrich entities with prices, rewards, labels, and nested vaults.
+11. [Account Computed Properties](./docs/account-computed-properties.md) - Health factor/LTV/net-value computed fields and data prerequisites.
+12. [Caching External Data Queries](./docs/caching-external-data-queries.md) - `query*` decoration pattern for caching/logging/profiling.
+13. [Plugins](./docs/plugins.md) - Plugin system for read-path and plan-path extensions.
+14. [Labels](./docs/labels.md) - Label metadata model and usage.
+15. [Decoding Smart Contract Errors](./docs/decode-smart-contract-errors.md) - Revert decoding utilities for better error handling.
+16. [Entity Diagnostics](./docs/entity-diagnostics.md) - Sidecar metadata for data normalization, fallbacks, and per-field warnings.
+
+## Examples
+
+Runnable examples are in [`./examples`](./examples), including end-to-end execution flows and simulations against a fork.
+
+Comparison, parity-check, and other test-oriented scripts and reports live under [`./test/parity`](./test/parity).
+
+## Release Process
+
+This package is published via GitHub Actions, not by running `npm publish` locally.
+
+1. Open a PR targeting `main` that bumps the version in [`package.json`](./package.json).
+2. Update [`CHANGELOG.md`](./CHANGELOG.md) and refresh [`RELEASE_NOTES.md`](./RELEASE_NOTES.md) in the same PR.
+3. Let the `Validate euler-v2-sdk PR` workflow pass. It enforces that the package version changed and runs `release:check`.
+4. Merge the PR. The `Release euler-v2-sdk` workflow runs automatically on the merge commit, publishes the package to npm, creates the `euler-v2-sdk-v<version>` tag, and creates a GitHub release.

package/dist/src/entities/Account.d.ts

@@ -0,0 +1,242 @@
+import { type Address } from "viem";
+import type { VaultEntity } from "../services/vaults/vaultMetaService/index.js";
+import type { IVaultMetaService } from "../services/vaults/vaultMetaService/index.js";
+import type { VaultFetchOptions } from "../services/vaults/index.js";
+import type { PriceWad } from "./ERC4626Vault.js";
+import type { IPriceService } from "../services/priceService/index.js";
+import type { IRewardsService, UserReward } from "../services/rewardsService/index.js";
+import type { DataIssue } from "../utils/entityDiagnostics.js";
+import type { SubAccountRoe } from "../utils/accountComputations.js";
+export type AddressPrefix = `0x${string}`;
+/** Base interface for vault-like values (has `address`). Used as generic constraint so custom vault entity types work. */
+export interface IHasVaultAddress {
+    address: Address;
+}
+/** Default vault entity type (EVault | EulerEarn | SecuritizeCollateralVault). Use as IVaultEntity in the SDK. */
+export type IVaultEntity = VaultEntity;
+export interface AccountPopulated {
+    vaults: boolean;
+    marketPrices: boolean;
+    userRewards: boolean;
+}
+export interface AssetValue {
+    liquidation: bigint;
+    borrowing: bigint;
+    oracleMid: bigint;
+}
+export type DaysToLiquidation = "Infinity" | "MoreThanAYear" | number;
+/** Vault is only ever a vault entity type (EVault, EulerEarn, SecuritizeCollateralVault, or custom). Use generic = never for unresolved (vault omitted). */
+export interface AccountLiquidityCollateral<TVaultEntity extends IHasVaultAddress = never> {
+    address: Address;
+    vault?: TVaultEntity;
+    value: AssetValue;
+    /** USD price per underlying asset (18 dec WAD). Populated by `populateMarketPrices`. */
+    marketPriceUsd?: PriceWad;
+    /** Collateral value in USD (18 dec). Computed from `value.oracleMid * uoaUsdRate / 1e18`. */
+    valueUsd?: bigint;
+}
+/** Raw liquidity data shape (returned by data sources). */
+export interface IAccountLiquidity<TVaultEntity extends IHasVaultAddress = never> {
+    vaultAddress: Address;
+    vault?: TVaultEntity;
+    unitOfAccount: Address;
+    daysToLiquidation: DaysToLiquidation;
+    liabilityValue: AssetValue;
+    totalCollateralValue: AssetValue;
+    collaterals: AccountLiquidityCollateral<TVaultEntity>[];
+    /** Liability value in USD (18 dec). Populated by `populateMarketPrices`. */
+    liabilityValueUsd?: bigint;
+    /** Total collateral value in USD (18 dec). Populated by `populateMarketPrices`. */
+    totalCollateralValueUsd?: bigint;
+    /** Per-collateral liquidation price multipliers (WAD). Computed getter on AccountLiquidity class. */
+    readonly collateralLiquidationPrices?: Record<Address, bigint>;
+    /** Borrow liquidation price multiplier (WAD). `> 1` = safe margin. Computed getter on AccountLiquidity class. */
+    readonly borrowLiquidationPrice?: bigint;
+}
+/** AccountLiquidity with computed getters for liquidation prices. */
+export declare class AccountLiquidity<TVaultEntity extends IHasVaultAddress = never> implements IAccountLiquidity<TVaultEntity> {
+    vaultAddress: Address;
+    vault?: TVaultEntity;
+    unitOfAccount: Address;
+    daysToLiquidation: DaysToLiquidation;
+    liabilityValue: AssetValue;
+    totalCollateralValue: AssetValue;
+    collaterals: AccountLiquidityCollateral<TVaultEntity>[];
+    liabilityValueUsd?: bigint;
+    totalCollateralValueUsd?: bigint;
+    constructor(data: IAccountLiquidity<TVaultEntity>);
+    /** Per-collateral liquidation price multipliers (WAD). */
+    get collateralLiquidationPrices(): Record<Address, bigint>;
+    /** Borrow liquidation price multiplier (WAD). `> 1` = safe margin. */
+    get borrowLiquidationPrice(): bigint | undefined;
+}
+export interface IAccountPosition<TVaultEntity extends IHasVaultAddress = never> {
+    account: Address;
+    vaultAddress: Address;
+    /** Resolved vault entity only (never Address). Omitted when unresolved. */
+    vault?: TVaultEntity;
+    asset: Address;
+    shares: bigint;
+    assets: bigint;
+    borrowed: bigint;
+    isController: boolean;
+    isCollateral: boolean;
+    balanceForwarderEnabled: boolean;
+    liquidity?: IAccountLiquidity<TVaultEntity>;
+    /** USD price per underlying asset (18 dec WAD). Populated by `populateMarketPrices`. */
+    marketPriceUsd?: PriceWad;
+    /** Supplied value in USD (18 dec). `assets * marketPriceUsd / 10^decimals`. */
+    suppliedValueUsd?: bigint;
+    /** Borrowed value in USD (18 dec). `borrowed * marketPriceUsd / 10^decimals`. */
+    borrowedValueUsd?: bigint;
+    /** Borrow liquidation price in USD (18 dec WAD). Computed getter on positions. */
+    readonly borrowLiquidationPriceUsd?: bigint;
+    /** Per-collateral liquidation price in USD (18 dec WAD). Computed getter on positions. */
+    readonly collateralLiquidationPricesUsd?: Record<Address, bigint>;
+    /** Per-collateral liquidation price in USD (18 dec WAD). Computed getter on positions. (Legacy typo alias) */
+    readonly collateralLiqiidationPricesUsd?: Record<Address, bigint>;
+}
+export declare class AccountPosition<TVaultEntity extends IHasVaultAddress = never> implements IAccountPosition<TVaultEntity> {
+    account: Address;
+    vaultAddress: Address;
+    vault?: TVaultEntity;
+    asset: Address;
+    shares: bigint;
+    assets: bigint;
+    borrowed: bigint;
+    isController: boolean;
+    isCollateral: boolean;
+    balanceForwarderEnabled: boolean;
+    liquidity?: IAccountLiquidity<TVaultEntity>;
+    marketPriceUsd?: PriceWad;
+    suppliedValueUsd?: bigint;
+    borrowedValueUsd?: bigint;
+    constructor(data: IAccountPosition<TVaultEntity>);
+    get borrowLiquidationPriceUsd(): bigint | undefined;
+    get collateralLiquidationPricesUsd(): Record<Address, bigint> | undefined;
+    get collateralLiqiidationPricesUsd(): Record<Address, bigint> | undefined;
+}
+/** Raw sub-account data shape (returned by data sources). */
+export interface ISubAccount<TVaultEntity extends IHasVaultAddress = never> {
+    timestamp: number;
+    account: Address;
+    owner: Address;
+    lastAccountStatusCheckTimestamp: number;
+    /** Always addresses; only positions and liquidity collaterals get resolved vault entities. */
+    enabledControllers: Address[];
+    /** Always addresses; only positions and liquidity collaterals get resolved vault entities. */
+    enabledCollaterals: Address[];
+    positions: IAccountPosition<TVaultEntity>[];
+    /** Health factor (WAD). `> 1e18` = healthy. Computed getter on SubAccount class. */
+    readonly healthFactor?: bigint;
+    /** Current LTV (WAD). `liabilityValue / totalCollateralValue`. Computed getter on SubAccount class. */
+    readonly currentLTV?: bigint;
+    /** Weighted-average liquidation LTV threshold (WAD). Computed getter on SubAccount class. */
+    readonly liquidationLTV?: bigint;
+    /** Leverage multiplier (WAD, 1e18 = 1x). Requires USD data. Computed getter on SubAccount class. */
+    readonly multiplier?: bigint;
+    /** Total collateral value in USD (18 dec). Requires USD data. Computed getter on SubAccount class. */
+    readonly totalCollateralValueUsd?: bigint;
+    /** Liability value in USD (18 dec). Requires USD data. Computed getter on SubAccount class. */
+    readonly liabilityValueUsd?: bigint;
+    /** Net value in USD (18 dec): sum(supplied) - sum(borrowed). Computed getter on SubAccount class. */
+    readonly netValueUsd?: bigint;
+    /** ROE breakdown (decimal fractions). Requires populated vaults + market prices. Computed getter on SubAccount class. */
+    readonly roe?: SubAccountRoe;
+}
+/** SubAccount with computed getters for risk metrics. */
+export declare class SubAccount<TVaultEntity extends IHasVaultAddress = never> implements ISubAccount<TVaultEntity> {
+    timestamp: number;
+    account: Address;
+    owner: Address;
+    lastAccountStatusCheckTimestamp: number;
+    enabledControllers: Address[];
+    enabledCollaterals: Address[];
+    positions: AccountPosition<TVaultEntity>[];
+    constructor(data: ISubAccount<TVaultEntity>);
+    /** Health factor (WAD). `> 1e18` = healthy. */
+    get healthFactor(): bigint | undefined;
+    /** Current LTV (WAD). `liabilityValue / totalCollateralValue`. */
+    get currentLTV(): bigint | undefined;
+    /** Weighted-average liquidation LTV threshold (WAD). */
+    get liquidationLTV(): bigint | undefined;
+    /** Leverage multiplier (WAD, 1e18 = 1x). Requires USD data. */
+    get multiplier(): bigint | undefined;
+    /** Total collateral value in USD (18 dec). Requires USD data. */
+    get totalCollateralValueUsd(): bigint | undefined;
+    /** Liability value in USD (18 dec). Requires USD data. */
+    get liabilityValueUsd(): bigint | undefined;
+    /** Net value in USD (18 dec): sum(supplied) - sum(borrowed). */
+    get netValueUsd(): bigint | undefined;
+    /** ROE breakdown (decimal fractions, 0.05 = 5%). Requires populated vaults + market prices. */
+    get roe(): SubAccountRoe | undefined;
+}
+export type SubAccountsMap<TVaultEntity extends IHasVaultAddress = never> = Partial<Record<Address, SubAccount<TVaultEntity>>>;
+export interface IAccount<TVaultEntity extends IHasVaultAddress = never> {
+    chainId: number;
+    owner: Address;
+    subAccounts: Partial<Record<Address, ISubAccount<TVaultEntity>>>;
+    isLockdownMode?: boolean;
+    isPermitDisabledMode?: boolean;
+    populated?: Partial<AccountPopulated>;
+}
+export declare class Account<TVaultEntity extends IHasVaultAddress = never> implements IAccount<TVaultEntity> {
+    chainId: number;
+    owner: Address;
+    isLockdownMode: boolean;
+    isPermitDisabledMode: boolean;
+    subAccounts: SubAccountsMap<TVaultEntity>;
+    /** Per-user unclaimed rewards from Merkl/Brevis. Populated by `populateUserRewards`. */
+    userRewards?: UserReward[];
+    populated: AccountPopulated;
+    constructor(account: IAccount<TVaultEntity>);
+    getSubAccount(account: Address): SubAccount<TVaultEntity> | undefined;
+    getSubAccountById(id: number): SubAccount<TVaultEntity> | undefined;
+    getPosition(account: Address, vault: Address): AccountPosition<TVaultEntity> | undefined;
+    /**
+     * Returns true if the given vault is enabled as collateral for the sub-account.
+     * Returns false when sub-account is not available.
+     */
+    isCollateralEnabled(subAccountAddress: Address, vault: Address): boolean;
+    /**
+     * Returns true if the given vault is enabled as controller for the sub-account.
+     * Returns false when sub-account is not available.
+     */
+    isControllerEnabled(subAccountAddress: Address, vault: Address): boolean;
+    /**
+     * Returns the current controller vault address for the sub-account (there can only be one).
+     * Returns undefined when sub-account is not available or has no controller enabled.
+     */
+    getCurrentController(subAccountAddress: Address): Address | undefined;
+    /**
+     * Fetches vault entities from the service and maps them onto positions and liquidity collaterals.
+     * Mutates in place and returns diagnostics from vault fetching/enrichment.
+     */
+    populateVaults<TResolved extends IHasVaultAddress>(vaultMetaService: IVaultMetaService<TResolved>, options?: VaultFetchOptions): Promise<DataIssue[]>;
+    /** Maps fetched vault entities onto positions and liquidity collaterals. Mutates in place. */
+    mapVaultsToPositions<TResolved extends IHasVaultAddress>(vaults: Array<TResolved | undefined>): Account<TResolved>;
+    /**
+     * Populates USD market prices on positions and liquidity data.
+     * Requires `populateVaults` to have been called first (vault entities must be resolved).
+     * Mutates in place and returns diagnostics.
+     */
+    populateMarketPrices(priceService: IPriceService): Promise<DataIssue[]>;
+    /** Sum of `suppliedValueUsd` across all positions. `undefined` if no USD data populated. */
+    get totalSuppliedValueUsd(): bigint | undefined;
+    /** Sum of `borrowedValueUsd` across all positions. `undefined` if no USD data populated. */
+    get totalBorrowedValueUsd(): bigint | undefined;
+    /** Net asset value in USD: totalSupplied - totalBorrowed. `undefined` if no USD data populated. */
+    get netAssetValueUsd(): bigint | undefined;
+    /** Total unclaimed rewards value in USD (18 dec). `undefined` if no user rewards populated. */
+    get totalRewardsValueUsd(): bigint | undefined;
+    /**
+     * Fetches per-user unclaimed rewards from Merkl and Brevis providers.
+     * Populates `this.userRewards`.
+     */
+    populateUserRewards(rewardsService: IRewardsService): Promise<DataIssue[]>;
+    /**
+     * Replaces subAccounts with a map built from the given sub-accounts (keyed by account address).
+     * Use in examples or when building account state from fetched sub-accounts.
+     */
+    updateSubAccounts(...subAccounts: SubAccount<TVaultEntity>[]): void;
+}