@kehtus/proportion-sdk 0.1.0

package/SDK_IMPROVEMENT_PLAN.md

@@ -0,0 +1,197 @@
+# План улучшения Proportion SDK
+
+## Статус после повторной сверки
+
+Этот документ обновлён после повторной проверки against:
+
+- `contracts/MainVault.sol`
+- `contracts/FundedAccount.sol`
+- `contracts/FundedAccountFactory.sol`
+- `prop-sdk/src/*`
+- критичные indexer-файлы `envio-funded/schema.graphql` и `envio-funded/src/EventHandlers.ts`
+
+Если этот план и Solidity расходятся, Solidity остаётся source of truth.
+
+## Что уже закрыто
+
+### Контрактная синхронизация
+
+- ABI в SDK синхронизированы с текущими локальными контрактами.
+- Формулы `activationFee`, `subscriptionFee`, `splitProfit`, `trailingFloor`, `dailyFloor` приведены к актуальной Solidity-логике.
+- `arch.md` обновлён и теперь описывает текущий surface SDK, а не старую версию контрактов.
+
+### VaultModule
+
+- Добавлены admin setters для текущих mutable параметров vault:
+  - `setFeeMultiplier`
+  - `setSubscriptionFeeMultiplier`
+  - `setHypeForSpot`
+  - `setMaxCap`
+  - `setMinBuilderShares`
+  - `setBuilderLeverage`
+  - `setProtocolFeeBps`
+  - `setMinAccountSize`
+  - `setMaxAccountSize`
+  - `setMinDrawdownBps`
+  - `setMaxDrawdownBps`
+  - `setMaxUtilizationBps`
+  - `setMaxSingleAccountBps`
+- `getStats()` расширен и читает текущий конфиг и runtime state vault.
+- Добавлены utility getters:
+  - `isFundedAccount`
+  - `getDelegateBuilder`
+  - `getRemainingCap`
+- `activateFunded()` больше не полагается на stale native fee default и читает `hypeForSpot()` из vault.
+
+### AccountModule
+
+- Добавлен `initiateCloseAdmin`.
+- Добавлен `getAccountConfig()`.
+- `getDetails()` теперь возвращает `subscriptionFeeMultiplier`, `checkpointIndex` и нормализованные checkpoints вместо сырого ring-buffer порядка.
+- Текущий write surface выровнен с локальным `FundedAccount.sol`.
+
+### FactoryModule
+
+- SDK переведён на реальный on-chain surface новой фабрики:
+  - `allAccounts(index)`
+  - `allAccountsIndex(account)`
+  - `traderBuilderNonce(owner, builder)`
+  - `predictFundedAccountAddress(owner, builder)`
+- Сохранены совместимые helper-методы `getAccountsCount()` и `getAccounts()`, но теперь они реализованы поверх probing `allAccounts(index)`.
+- Добавлены safe helpers:
+  - `hasAccount`
+  - `findAccountIndex`
+
+### Indexer Layer
+
+- GraphQL-типы приведены к реальной `schema.graphql`.
+- Разделены on-chain state labels и indexer state labels.
+- Учтён `POSITION_LEVERAGE`.
+- Учтены дополнительные индексируемые поля вроде `subscriptionFeeMultiplier`, `lastWithdrawalId`, `totalAllocated`, `totalShares`.
+- Vault analytics больше не должны опираться на жёстко зашитый 90/10 split: актуальны `protocolFeeReceiver`, mutable `PROTOCOL_FEE_BPS` и фактический amount, остающийся в vault.
+- Для service/backend use cases добавлена инъекция `fetchFn` и `webSocketCtor`, чтобы SDK не зависел жёстко от глобальных runtime объектов.
+
+## Что в старом плане устарело
+
+### Устаревшие статусы
+
+Следующие пункты были верны для прошлой версии SDK, но уже закрыты:
+
+- отсутствие `initiateCloseAdmin`
+- отсутствие `getAccountConfig`
+- отсутствие большинства admin setters в `VaultModule`
+- неполный `VaultStats`
+- отсутствие `isFundedAccount` и `getDelegateBuilder`
+
+### Устаревшие константы
+
+В старом плане были значения, которые больше не совпадают с текущими контрактами:
+
+- `MIN_PROFIT_BPS` указан как `150`, но в текущем `FundedAccount.sol` он равен `50`
+- важные экспортируемые значения нужно сверять с локальной Solidity, а не со старым plan draft
+
+### Необязательная рекомендация про отдельный `AdminModule`
+
+Идея отдельного `AdminModule` сама по себе нормальная, но сейчас это не must-have.
+Текущий `VaultModule` уже покрывает актуальный owner admin surface без архитектурного долга, который требовал бы срочного выделения нового модуля.
+
+## Что остаётся актуальным
+
+### Phase 2. Улучшения API и DX
+
+1. Выровнять числовую модель SDK для service use cases.
+Сейчас часть helper-ов (`fromUsdc`, `from8Dec`, `formatUsd`) переводит `bigint` в `number`, что удобно для UI, но не идеально для финансовой серверной логики.
+
+2. Выровнять timestamp-модель.
+Сейчас часть временных полей в `AccountDetails` хранится как `bigint`, часть как `number`. Лучше выбрать одну ясную стратегию API.
+
+3. Добавить типы для параметризуемого admin-конфига.
+Практичный следующий шаг:
+
+```ts
+export interface VaultParameters {
+  feeMultiplier: number;
+  subscriptionFeeMultiplier: number;
+  minBuilderShares: bigint;
+  builderLeverage: bigint;
+  protocolFeeBps: bigint;
+  minAccountSize: bigint;
+  maxAccountSize: bigint;
+  minDrawdownBps: number;
+  maxDrawdownBps: number;
+  maxUtilizationBps: bigint;
+  maxSingleAccountBps: bigint;
+  hypeForSpot: bigint;
+  maxCap: bigint;
+}
+```
+
+4. Добавить validation helpers поверх текущего `VaultStats`.
+Это уже полезный SDK-level слой, который не зависит от деплоя:
+
+```ts
+export function validateAccountSize(size: bigint, vaultStats: VaultStats): {
+  valid: boolean;
+  reason?: string;
+}
+
+export function validateDrawdownBps(bps: number, vaultStats: VaultStats): {
+  valid: boolean;
+  reason?: string;
+}
+
+export function canBuilderActivate(
+  builderInfo: BuilderInfo,
+  accountSize: bigint,
+  vaultStats: VaultStats
+): {
+  canActivate: boolean;
+  reason?: string;
+}
+```
+
+### Phase 3. Дополнительные helper-обёртки
+
+1. Batch reads:
+
+```ts
+async getMultipleLPPositions(addresses: Address[]): Promise<LPPosition[]>
+async getMultipleBuilderInfo(addresses: Address[]): Promise<BuilderInfo[]>
+async getMultipleAccountDetails(addresses: Address[]): Promise<AccountDetails[]>
+```
+
+2. Дополнительные indexer helpers:
+
+```ts
+async getEventsByDateRange(
+  accountAddress: Address,
+  fromDate: Date,
+  toDate: Date
+): Promise<GqlAccountEvent[]>
+
+async getCheckpointHistory(
+  accountAddress: Address,
+  limit?: number
+): Promise<GqlCheckpoint[]>
+```
+
+3. Higher-level admin ergonomics:
+
+- `getCurrentParameters()`
+- `validateParameters()`
+- опциональный bulk-update helper для owner workflows
+
+## Рекомендуемый следующий порядок работ
+
+1. Сначала привести numeric/timestamp API к более строгой и единообразной модели.
+2. Затем добавить validation helpers поверх уже актуального `VaultStats`.
+3. После этого расширять batch helpers и high-level admin ergonomics.
+
+## Проверка
+
+После последних изменений:
+
+- `npm run check` проходит
+- `npm run test:unit` проходит
+
+RPC/GraphQL-зависимые тесты не считаются источником истины, пока локальные контракты не задеплоены.

package/arch.md

@@ -0,0 +1,448 @@
+# Proportion SDK
+
+TypeScript SDK over the current local Proportion Solidity contracts.
+
+This document is intentionally aligned to the code in:
+
+- `contracts/MainVault.sol`
+- `contracts/FundedAccount.sol`
+- `contracts/FundedAccountFactory.sol`
+- `prop-sdk/src/*`
+
+If documentation and Solidity diverge, Solidity is the source of truth.
+
+## Architecture
+
+The SDK has four runtime modules:
+
+- `vault`: `MainVault` reads, LP flows, builder flows, and owner admin writes.
+- `account`: `FundedAccount` reads and writes for a specific funded account clone.
+- `factory`: `FundedAccountFactory` helpers around deterministic account addresses and factory state.
+- `indexer`: optional Envio GraphQL/WebSocket client for off-chain querying and subscriptions.
+
+`ProportionSDK` itself is a thin composition layer over `viem`.
+
+## Initialization
+
+```ts
+import { ProportionSDK, hyperEvm } from "@proportion/sdk";
+import { createWalletClient, http } from "viem";
+import { privateKeyToAccount } from "viem/accounts";
+
+const wallet = createWalletClient({
+  account: privateKeyToAccount("0x..."),
+  chain: hyperEvm,
+  transport: http(),
+});
+
+const sdk = new ProportionSDK({
+  graphqlUrl: "https://your-envio-endpoint/graphql",
+  walletClient: wallet,
+});
+```
+
+There are two construction modes:
+
+- `new ProportionSDK(config)`: uses addresses from `config.addresses` or `src/constants.ts`.
+- `await ProportionSDK.create(config)`: resolves addresses in this order:
+  1. `config.addresses`
+  2. `PROPORTION_VAULT_ADDRESS`, `PROPORTION_FACTORY_ADDRESS`, `PROPORTION_USDC_ADDRESS`
+  3. `indexer.getProtocolConfig()`
+  4. if vault is already known but `USDC` is missing, `usdc()` is read from `MainVault`
+  5. hardcoded SDK defaults
+
+Best practice:
+
+- Prefer explicit `config.addresses` or ENV in applications and services.
+- Treat `indexer.getProtocolConfig()` as a convenience fallback, not as the primary source of deployment addresses.
+- Use `new ProportionSDK(config)` when you already know the full address set and want direct construction without async resolution.
+
+## Config
+
+```ts
+interface SDKConfig {
+  graphqlUrl: string;
+  graphqlWsUrl?: string;
+  rpcUrl?: string;
+  walletClient?: WalletClient;
+  fetchFn?: typeof fetch;
+  webSocketCtor?: WebSocketConstructor;
+  addresses?: {
+    MAIN_VAULT?: string;
+    FACTORY?: string;
+    USDC?: string;
+  };
+}
+```
+
+For service or server integrations, `fetchFn` and `webSocketCtor` can be injected explicitly instead of relying on global runtime objects.
+
+The exported addresses in `src/constants.ts` are SDK defaults for the current environment, not a guarantee of future deployments.
+
+## Modules
+
+### `prop.vault`
+
+Reads:
+
+```ts
+const stats = await prop.vault.getStats();
+const position = await prop.vault.getLPPosition("0x...");
+const builder = await prop.vault.getBuilderInfo("0x...");
+const perps = await prop.vault.getAllowedPerps();
+const allowed = await prop.vault.isAllowedPerp(0);
+const fee = await prop.vault.calculateFee(toUsdc(5000), 500, false);
+const paused = await prop.vault.isPaused();
+const remainingCap = await prop.vault.getRemainingCap();
+const isFa = await prop.vault.isFundedAccount("0x...");
+const delegatedTo = await prop.vault.getDelegateBuilder("0x...");
+```
+
+`getStats()` returns both operational metrics and current mutable vault config:
+
+```ts
+type VaultStats = {
+  totalAssets: bigint;
+  sharePrice: bigint;
+  utilizationBps: bigint;
+  availableForAllocation: bigint;
+  maxAccountSize: bigint;
+  remainingCap: bigint;
+  paused: boolean;
+  feeMultiplier: number;
+  subscriptionFeeMultiplier: number;
+  totalShares: bigint;
+  totalAllocated: bigint;
+  owner: Address;
+  pendingOwner: Address;
+  relayer: Address;
+  protocolFeeReceiver: Address;
+  maxCap: bigint;
+  hypeForSpot: bigint;
+  factory: Address;
+  minBuilderShares: bigint;
+  builderLeverage: bigint;
+  protocolFeeBps: bigint;
+  minAccountSize: bigint;
+  maxAccountSizeLimit: bigint;
+  minDrawdownBps: number;
+  maxDrawdownBps: number;
+  maxUtilizationBps: bigint;
+  maxSingleAccountBps: bigint;
+  dailyDdDiscountBps: number;
+};
+```
+
+Writes:
+
+```ts
+await prop.vault.approveUsdc(toUsdc(1000));
+await prop.vault.deposit(toUsdc(1000));
+await prop.vault.withdraw(shareAmount);
+
+await prop.vault.registerBuilder();
+await prop.vault.setDelegate("0x...");
+await prop.vault.removeDelegate("0x...");
+
+await prop.vault.activateFunded({
+  trader: "0x...",
+  accountSize: toUsdc(5000),
+  drawdownBps: 500,
+  dailyDrawdownEnabled: false,
+});
+```
+
+`activateFunded()` now reads `hypeForSpot()` from the vault when `hypeValue` is not supplied, so the SDK follows the current contract config instead of hardcoding a stale native value.
+
+Admin writes covered by the SDK:
+
+```ts
+await prop.vault.pause();
+await prop.vault.unpause();
+await prop.vault.setRelayer("0x...");
+await prop.vault.setFactory("0x...");
+await prop.vault.setProtocolFeeReceiver("0x...");
+await prop.vault.setFeeMultiplier(120);
+await prop.vault.setSubscriptionFeeMultiplier(150);
+await prop.vault.setHypeForSpot(1_000_000_000_000_000n);
+await prop.vault.setMaxCap(0n);
+await prop.vault.setMinBuilderShares(toUsdc(10));
+await prop.vault.setBuilderLeverage(10n);
+await prop.vault.setProtocolFeeBps(1000n);
+await prop.vault.setMinAccountSize(toUsdc(10));
+await prop.vault.setMaxAccountSize(toUsdc(50_000));
+await prop.vault.setMinDrawdownBps(500);
+await prop.vault.setMaxDrawdownBps(2500);
+await prop.vault.setMaxUtilizationBps(8000n);
+await prop.vault.setMaxSingleAccountBps(1000n);
+await prop.vault.setDailyDdDiscountBps(2000);
+await prop.vault.addAllowedPerp(4);
+await prop.vault.removeAllowedPerp(4);
+await prop.vault.transferOwnership("0x...");
+await prop.vault.acceptOwnership();
+```
+
+### `prop.account`
+
+Reads:
+
+```ts
+const details = await prop.account.getDetails("0xAccount");
+const state = await prop.account.getState("0xAccount");
+const trailing = await prop.account.getTrailingFloor("0xAccount");
+const daily = await prop.account.getDailyFloor("0xAccount");
+const canWithdraw = await prop.account.canWithdrawProfit("0xAccount");
+const subActive = await prop.account.isSubscriptionActive("0xAccount");
+const checkpoints = await prop.account.getCheckpoints("0xAccount");
+const pending = await prop.account.getPendingWithdrawal("0xAccount");
+const config = await prop.account.getAccountConfig("0xAccount");
+```
+
+`getDetails()` includes the current per-account `subscriptionFeeMultiplier`, exposes `checkpointIndex`, and normalizes the on-chain checkpoint ring buffer into chronological order.
+
+Writes:
+
+```ts
+await prop.account.setApiWallet("0xAccount", "0xWallet");
+await prop.account.setRiskEngineWallet("0xAccount", "0xWallet");
+await prop.account.requestWithdrawProfit("0xAccount");
+await prop.account.cancelSubscription("0xAccount");
+await prop.account.cancelStuckWithdrawal("0xAccount");
+
+await prop.account.checkpoint("0xAccount");
+await prop.account.initiateClose("0xAccount");
+await prop.account.initiateCloseForPerp("0xAccount", 0);
+await prop.account.initiateCloseAdmin("0xAccount");
+await prop.account.closeAndReturn("0xAccount");
+await prop.account.finalizeReturn("0xAccount");
+await prop.account.claimWithdrawal("0xAccount");
+await prop.account.claimSubscriptionFee("0xAccount");
+await prop.account.rescueStuckFunds("0xAccount");
+```
+
+`setRiskEngineWallet()` maps to the current contract behavior in which the same method is used by the protocol relayer and by the builder; on-chain access control decides which of `riskEngineWallet` or `builderRiskEngineWallet` is updated.
+
+### `prop.factory`
+
+Canonical on-chain surface of the current factory:
+
+- `predictFundedAccountAddress(owner, builder)`
+- `allAccounts(index)`
+- `allAccountsIndex(account)`
+- `traderBuilderNonce(owner, builder)`
+- public config getters such as `implementation`, `owner`, `pendingOwner`, `usdc`, and `vault`
+
+SDK helpers:
+
+```ts
+const predicted = await prop.factory.predictAddress(owner, builder);
+const nonce = await prop.factory.getTraderBuilderNonce(owner, builder);
+const account0 = await prop.factory.getAccountAt(0n);
+const index = await prop.factory.getAccountIndex(account0);
+const exists = await prop.factory.hasAccount(account0);
+const safeIndex = await prop.factory.findAccountIndex(account0);
+const cfg = await prop.factory.getConfig();
+```
+
+For backwards compatibility, the SDK still exposes:
+
+```ts
+const count = await prop.factory.getAccountsCount();
+const page = await prop.factory.getAccounts(0n, 10n);
+```
+
+These are now implemented in the SDK by probing `allAccounts(index)` because the current Solidity factory does not expose explicit `getAccountsCount()` or paginated `getAccounts()` functions.
+
+### `prop.indexer`
+
+GraphQL queries:
+
+```ts
+await prop.indexer.getVault();
+await prop.indexer.getLP("0x...");
+await prop.indexer.getLPDeposits("0x...", { limit: 20, offset: 0 });
+await prop.indexer.getLPWithdrawals("0x...");
+await prop.indexer.getBuilder("0x...");
+await prop.indexer.getBuilder("0x...", "0xVault...");
+await prop.indexer.getDelegates("0x...");
+await prop.indexer.getDelegates("0x...", "0xVault...");
+await prop.indexer.getAccount("0x...");
+await prop.indexer.getAccountsByOwner("0x...");
+await prop.indexer.getAccountsByBuilder("0x...");
+await prop.indexer.getAccountsByBuilder("0x...", "0xVault...");
+await prop.indexer.getAccountsByState("ACTIVE");
+await prop.indexer.getAccountsByStates(["ACTIVE", "CLOSING"]);
+await prop.indexer.getAccountsUpdatedSince("1709500000");
+await prop.indexer.getCheckpoints("0x...");
+await prop.indexer.getWithdrawals("0x...");
+await prop.indexer.getSubscriptionPayments("0x...");
+await prop.indexer.getEvents("0x...");
+await prop.indexer.getEventsByType("Initialized", 5);
+await prop.indexer.getProtocolConfig();
+await prop.indexer.getMainVaultConfig();
+await prop.indexer.getFactoryConfig();
+await prop.indexer.getConfigChanges({ field: "protocolFeeBps", limit: 20 });
+await prop.indexer.getVaultDayData();
+await prop.indexer.getVaultDayData("0xVault...", { limit: 30 });
+await prop.indexer.getLPDayData("0x...");
+await prop.indexer.getAllowedPerps();
+await prop.indexer.getAllowedPerps("0xVault...");
+```
+
+When `vaultAddress` is omitted, `getVault()`, `getMainVaultConfig()`, `getBuilder()`, `getDelegates()`, `getAccountsByBuilder()`, `getVaultDayData()`, and `getAllowedPerps()` default to the active vault from `ProtocolConfig`.
+This is a convenience default only; production callers can pass `vaultAddress` explicitly to avoid hidden address resolution.
+
+When `factoryAddress` is omitted, `getFactoryConfig()` defaults to the active factory from `ProtocolConfig`.
+This is a convenience default only; production callers can pass `factoryAddress` explicitly to avoid hidden address resolution.
+
+The SDK indexer layer follows `envio-funded/schema.graphql`, not the on-chain enum surface directly. That means:
+
+- indexer account states start at `INITIALIZED`, not `UNINITIALIZED`
+- `breachType` includes `POSITION_LEVERAGE`
+- the SDK exposes address-keyed config/history entities like `MainVaultConfig`, `FactoryConfig`, `ConfigChange`, and `VaultDayData`
+- `Vault` and `FundedAccount` GraphQL objects expose extra indexed fields such as `totalAllocated`, `totalShares`, `subscriptionFeeMultiplier`, `lastWithdrawalId`, `closePendingSubFee`, `closePendingProfit`, `cumulativeActivationFeesToVault`, `cumulativeCancelledProfit`, `cumulativeProtocolFeesRouted`, `cumulativeHypercoreFees`, `cumulativeRescuedFunds`, `protocolFeeBps`, and `protocolFeeReceiver`
+- `LiquidityProviderDayData` exists in the current schema and is wrapped by the SDK, but the current indexer handlers do not populate it yet, so queries may legitimately return empty arrays
+
+Subscriptions:
+
+```ts
+const unsubActive = prop.indexer.subscribeActiveAccounts((accounts) => {});
+const unsubAccount = prop.indexer.subscribeAccount("0x...", (account) => {});
+const unsubEvents = prop.indexer.subscribeAccountEvents("0x...", (events) => {});
+const unsubStates = prop.indexer.subscribeStateChanges((accounts) => {});
+```
+
+Call `prop.disconnect()` to close all WebSocket state.
+
+## Utility Math
+
+The utility layer mirrors the current contract formulas.
+
+Decimals:
+
+```ts
+toUsdc(100);          // 100_000_000n
+fromUsdc(100_000_000n); // 100
+to8Dec(100_000_000n);   // 10_000_000_000n
+toUsdc6(10_000_000_000n); // 100_000_000n
+```
+
+Activation fee:
+
+```ts
+activationFee(toUsdc(5000), 500, false, 120);       // 300 USDC
+activationFee(toUsdc(5000), 500, true, 120, 2000); // 240 USDC
+```
+
+Formula:
+
+```text
+accountSize * drawdownBps * feeMultiplier / 1_000_000
+```
+
+The helper then rounds up to whole USDC units, matching the current contract behavior.
+
+If daily drawdown is enabled, the helper applies `dailyDdDiscountBps`:
+
+```text
+fee * (10000 - dailyDdDiscountBps) / 10000
+```
+
+`activationFee()` defaults `dailyDdDiscountBps` from `src/constants.ts`.
+For exact live parity with a deployed vault, pass `vault.getStats().dailyDdDiscountBps`.
+
+Subscription fee:
+
+```ts
+subscriptionFee(toUsdc(5000), 150); // 75 USDC
+```
+
+Canonical formula:
+
+```text
+accountSize * subscriptionFeeMultiplier / 10000
+```
+
+The helper rounds the result up to whole USDC units.
+
+The helper still accepts the legacy 4-argument signature for compatibility, but drawdown and daily-DD no longer affect the result because the current contracts do not use them in subscription pricing.
+
+Profit split:
+
+```ts
+const { owner, vault, protocol } = splitProfit(toUsdc(1000));
+// owner = 800
+// vault = 130
+// protocol = 70
+```
+
+State labels:
+
+```ts
+stateToLabel(AccountState.Uninitialized); // "UNINITIALIZED"
+labelToState("CLOSING");                  // AccountState.Closing
+```
+
+## Defaults vs Dynamic Config
+
+Two categories exist in the SDK:
+
+- Static source defaults exported from `src/constants.ts`.
+- Mutable on-chain config read from `MainVault`.
+
+Examples of values that can change on-chain through admin setters:
+
+- `feeMultiplier`
+- `subscriptionFeeMultiplier`
+- `MIN_BUILDER_SHARES`
+- `BUILDER_LEVERAGE`
+- `PROTOCOL_FEE_BPS`
+- `MIN_ACCOUNT_SIZE`
+- `MAX_ACCOUNT_SIZE`
+- `MIN_DRAWDOWN_BPS`
+- `MAX_DRAWDOWN_BPS`
+- `MAX_UTILIZATION_BPS`
+- `MAX_SINGLE_ACCOUNT_BPS`
+- `dailyDdDiscountBps`
+- `hypeForSpot`
+- `maxCap`
+
+Best practice:
+
+- Use exported constants for local validation defaults and tests.
+- Use `vault.getStats()` before showing risk, pricing, or activation constraints to users.
+
+## Testing
+
+```bash
+npm run check
+npm run test:unit
+npm run test:reads
+npm run test:lifecycle
+npm run test:indexer
+```
+
+Notes:
+
+- `test:unit` is fully local.
+- `test:reads`, `test:lifecycle`, and `test:indexer` require reachable RPC/GraphQL endpoints.
+- Current Foundry tests in `/test` are still on an older contract API and should not be treated as SDK source of truth until updated.
+
+## File Layout
+
+```text
+src/
+  sdk.ts
+  vault.ts
+  account.ts
+  factory.ts
+  indexer.ts
+  types.ts
+  constants.ts
+  utils.ts
+  index.ts
+  abi/
+    mainVault.ts
+    fundedAccount.ts
+    factory.ts
+```

package/dist/__tests__/account.test.d.ts

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

package/dist/__tests__/account.test.js

@@ -0,0 +1,36 @@
+import { describe, expect, it } from "vitest";
+import { normalizeCheckpoints } from "../account.js";
+describe("normalizeCheckpoints", () => {
+    it("keeps linear order before the ring buffer wraps", () => {
+        const checkpoints = [
+            { accountValue: 100n, timestamp: 1n, profitable: false },
+            { accountValue: 110n, timestamp: 2n, profitable: true },
+            { accountValue: 120n, timestamp: 3n, profitable: true },
+            { accountValue: 0n, timestamp: 0n, profitable: false },
+            { accountValue: 0n, timestamp: 0n, profitable: false },
+            { accountValue: 0n, timestamp: 0n, profitable: false },
+            { accountValue: 0n, timestamp: 0n, profitable: false },
+        ];
+        expect(normalizeCheckpoints(checkpoints, 3, 3).map((cp) => cp.accountValue)).toEqual([100n, 110n, 120n]);
+    });
+    it("returns chronological order after the ring buffer wraps", () => {
+        const checkpoints = [
+            { accountValue: 800n, timestamp: 8n, profitable: true },
+            { accountValue: 200n, timestamp: 2n, profitable: false },
+            { accountValue: 300n, timestamp: 3n, profitable: false },
+            { accountValue: 400n, timestamp: 4n, profitable: false },
+            { accountValue: 500n, timestamp: 5n, profitable: true },
+            { accountValue: 600n, timestamp: 6n, profitable: true },
+            { accountValue: 700n, timestamp: 7n, profitable: true },
+        ];
+        expect(normalizeCheckpoints(checkpoints, 7, 1).map((cp) => cp.accountValue)).toEqual([
+            200n,
+            300n,
+            400n,
+            500n,
+            600n,
+            700n,
+            800n,
+        ]);
+    });
+});

package/dist/__tests__/indexer.test.d.ts

@@ -0,0 +1 @@
+import "dotenv/config";