@kehtus/proportion-sdk 0.1.1 → 0.1.3

package/arch.md

@@ -1,455 +0,0 @@
-# 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.
-
-## Key Contract Integration Notes
-
-- **Single Managed Signer:** Only `apiWallet` exists on FundedAccount. It is set by the relayer via `setApiWallet()`. No `riskEngineWallet` or `builderRiskEngineWallet`.
-- **Unified Mode:** FundedAccount operates in Hyperliquid unified mode (shared spot + perp balance). Withdrawals use one-step `spotSend` instead of two-step `usdClassTransfer` + `spotSend`.
-- **6dec Account Values:** `accountMarginSummary` returns 6dec. `highWaterMark`, `dayStartValue`, and drawdown floors are all 6dec. `spotBalance` and `spotSend` use 8dec.
-- **Multi-DEX:** `PERP_DEX_COUNT = 2` replaces `PERP_DEX_INDEX = 0`. Account value is summed across all DEXes + spot.
-- **`bridgeToEvm()`** is restricted to `Returning` state only (retry `spotSend` for stuck funds during close flow).
-
-## 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"); // relayer-only
-await prop.account.requestWithdrawProfit("0xAccount");
-await prop.account.cancelSubscription("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.bridgeToEvm("0xAccount");       // Returning state only — retry spotSend
-await prop.account.finalizeReturn("0xAccount");
-await prop.account.claimWithdrawal("0xAccount");
-await prop.account.claimSubscriptionFee("0xAccount");
-await prop.account.rescueStuckFunds("0xAccount");
-```
-
-### `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 (6dec)
-fromUsdc(100_000_000n); // 100
-to8Dec(100_000_000n);   // 10_000_000_000n (6dec→8dec, for spotSend)
-toUsdc6(10_000_000_000n); // 100_000_000n (8dec→6dec)
-```
-
-Note: On-chain `highWaterMark`, `dayStartValue`, and drawdown floors are all 6dec (matching `accountMarginSummary` output). `spotBalance` and `spotSend` use 8dec.
-
-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

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

package/dist/__tests__/account.test.js

@@ -1,36 +0,0 @@
-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

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