@perena/vault-sdk 1.0.42 → 1.0.44

package/dist/index.d.ts

@@ -6508,8 +6508,9 @@ type Bankineco = {
                     {
                         name: "maxApyBps";
                         docs: [
-                            "Maximum annualized APY accepted between oracle NAV updates that advance",
-                            "the vault's regular performance-fee high-water mark, in basis points."
+                            "Maximum linear annualized growth of the settled regular share price",
+                            "against `max_apy_anchor`, for settlements advancing its performance-fee",
+                            "high-water mark. Basis points; zero disables enforcement, not observation."
                         ];
                         type: "u16";
                     },
@@ -6556,10 +6557,23 @@ type Bankineco = {
                         ];
                         type: "i64";
                     },
+                    {
+                        name: "maxApyAnchor";
+                        docs: [
+                            "Independent of the durable fixed-APY accrual anchor above. Carved from",
+                            "reserved bytes without changing APYConfig or Vault size/field offsets.",
+                            "Existing zero-filled accounts initialize lazily from a known price/time."
+                        ];
+                        type: {
+                            defined: {
+                                name: "maxApyAnchor";
+                            };
+                        };
+                    },
                     {
                         name: "padding1";
                         type: {
-                            array: ["u64", 32];
+                            array: ["u64", 28];
                         };
                     }
                 ];
@@ -7146,6 +7160,41 @@ type Bankineco = {
                 ];
             };
         },
+        {
+            name: "maxApyAnchor";
+            docs: [
+                "Weekly observations of the settled regular share price. Keep the previous",
+                "observation while the newest is younger than seven days, so rollover never",
+                "reduces a mature comparison window to a few seconds. With regular settlement",
+                "the effective lookback is seven to fourteen days; sparse settlement can make",
+                "it longer. A new cohort uses its actual age until seven days of history exist."
+            ];
+            serialization: "bytemuck";
+            repr: {
+                kind: "c";
+            };
+            type: {
+                kind: "struct";
+                fields: [
+                    {
+                        name: "sharePrice";
+                        type: "u64";
+                    },
+                    {
+                        name: "timestamp";
+                        type: "i64";
+                    },
+                    {
+                        name: "previousSharePrice";
+                        type: "u64";
+                    },
+                    {
+                        name: "previousTimestamp";
+                        type: "i64";
+                    }
+                ];
+            };
+        },
         {
             name: "pendingManagerWithdrawDestination";
             docs: [
@@ -12252,6 +12301,31 @@ interface SettlementSimulationSnapshot {
     junior?: SimulatedShareClass;
     senior?: SimulatedShareClass;
 }
+interface MaxApyAnchorSnapshot {
+    sharePrice: bigint;
+    timestamp: bigint;
+    previousSharePrice: bigint;
+    previousTimestamp: bigint;
+}
+/** Inputs to the program's linear annualized max-APY comparison. */
+interface RealizedApySimulation {
+    basis: "regular-share-price";
+    priorValue: bigint;
+    nextValue?: bigint;
+    priorTs: bigint;
+    timestampSource: "apy.max_apy_anchor.timestamp" | "apy.max_apy_anchor.previous_timestamp" | "legacy fixed-APY anchor (initialization)" | "current share-price observation (initialization)";
+    checkpointTs: bigint;
+    nowTs: bigint;
+    elapsedSecs: bigint;
+    /** Signed annualized growth, in millionths of a basis point, truncated. */
+    impliedApyMicroBps?: bigint;
+    /** Ceiling of the positive implied rate; zero for flat/negative growth. */
+    minimumCapBps?: bigint;
+    maxApyBps: number;
+    fixedApyBps: number;
+    hwmBefore: bigint;
+    hwmAfter: bigint;
+}
 /**
  * Result of replaying the relevant on-chain consensus and NAV-settlement math.
  * All numbers remain in raw on-chain fixed-point/base units.
@@ -12271,6 +12345,10 @@ interface SettlementSimulation {
     /** Per-holding attribution of the gross-NAV change consensus would cause. */
     navContributions: HoldingNavContribution[];
     grossNav?: bigint;
+    /** Also retained when max APY blocks the otherwise-projected settlement. */
+    realizedApy?: RealizedApySimulation;
+    /** Weekly observations after the projected settlement succeeds. */
+    projectedMaxApyAnchor?: MaxApyAnchorSnapshot;
     settledAccountingNav?: bigint;
     current: SettlementSimulationSnapshot;
     /**
@@ -12535,8 +12613,9 @@ interface LogProspectiveApyParams {
     log: (msg: string) => void;
 }
 /**
- * Fetch the current settlement timestamp and log the APY implied by the
- * prospective update, so MaxApyExceeded failures are diagnosable.
+ * @deprecated Raw candidate NAV estimate, retained for SDK compatibility.
+ * Use simulateDryRunSettlement + formatSettlementSimulation for the program's
+ * consensus-aware max-APY diagnostic, including regular-share and HWM rules.
  *
  * NAV is expressed in the vault's accounting unit (scaled by assetDecimals).
  * Mirrors `gross_nav_from_holdings`: consensus updates overlay their target
@@ -12561,8 +12640,8 @@ declare function discoverVaultsForSigner(client: VaultClient, signer: Keypair, o
 
 /**
  * Fail closed while any configured yield account has an unsettled payment.
- * The payout must be confirmed only after it is visible in the same wallet
- * balance source used by this service. Until then, no oracle update is safe.
+ * Confirmed payments reduce tracked value; the oracle does not add the payout's
+ * destination balance to the reported external amount.
  */
 declare function assertNoUnconfirmedYieldPayments(yieldTracker: YieldTracker | undefined, target: ConsensusOracleTarget): Promise<void>;
 /**
@@ -12785,6 +12864,7 @@ declare class MockYieldTracker implements YieldTracker {
  * file owns deterministic program-math parity and is straightforward to test.
  */
 
+declare const MAX_APY_ANCHOR_WINDOW_SECS = 604800n;
 interface SimulateSettlementArgs {
     vault: DecodedVault;
     oracleData: readonly number[];
@@ -12806,6 +12886,8 @@ declare function formatSettlementSimulation(simulation: SettlementSimulation): s
 
 interface LiveConsensusOracleDepsOptions {
     log?: (msg: string) => void;
+    /** @deprecated Ignored. Manager-wallet balance sourcing has been removed. */
+    rpcOnly?: boolean;
     includeExternalPositions?: boolean;
 }
 declare function createLiveConsensusOracleDeps(connection: Connection, opts?: LiveConsensusOracleDepsOptions): ConsensusOracleDeps;
@@ -12815,6 +12897,8 @@ interface RunLiveConsensusOracleOptions extends RunOptions {
     rpcUrl?: string;
     /** Override the vault program id. Defaults to the environment's configured program. */
     programId?: Address;
+    /** @deprecated Ignored. Manager-wallet balance sourcing has been removed. */
+    rpcOnly?: boolean;
     /** Include live Kamino/Marginfi positions in external amount updates. Defaults to true. */
     includeExternalPositions?: boolean;
 }
@@ -13149,4 +13233,4 @@ declare class TimelockSettlementService {
     private execute;
 }
 
-export { ASSET_DECIMALS, ASSET_REBALANCE_COOLDOWN_SECS, type AccountBalanceResponse, AccountClient, type AccountYieldResponse, ActivateCircuitBreakerBuilder, type ActivateCircuitBreakerIxArgs, type ActivateCircuitBreakerTxArgs, type AddAprCashflowUpdateParams, type AddCashflowUpdateParams, type AddIncentiveRecipientArgs, AddIncentiveRecipientBuilder, type AddIncentiveRecipientIxArgs, type AddNavCashflowUpdateParams, type AprAccountBalanceResponse, type AprAccountYieldResponse, type AssetPriceOracleConfigIxArgs, type AssetPriceOracleConfigTxArgs, type AssetPriceRefreshTarget, type AssetRefreshResult, type AssetType, BALANCE_CHANGE_BASELINE_MAX_AGE_SECS, type Bankineco, type BasicAuthCredentials, type Bigintish, type BuildMarginfiWithdrawInteractionArgs, CONSENSUS_ORACLE_VARIANT, type CancelIncentiveProposalArgs, CancelIncentiveProposalBuilder, CancelJuniorTrancheWithdrawBuilder, type CancelJuniorTrancheWithdrawIxArgs, type CancelJuniorTrancheWithdrawTxArgs, ClaimIncentiveBuilder, type ClaimIncentiveIxArgs, type ClaimIncentiveTxArgs, type Clock, type CollectSamplesOptions, type ConsensusAssetUpdate, type ConsensusHoldingEntry, type ConsensusHoldingSimulation, type ConsensusOracleDeps, type ConsensusOracleHoldingConfig, ConsensusOracleService, type ConsensusOracleTarget, CrankNavBuilder, type CrankNavIxArgs, type CrankNavTxArgs, CrankPerformanceFeesBuilder, type CrankPerformanceFeesIxArgs, type CrankPerformanceFeesTxArgs, type CreateAccountParams, CreateAssetHoldingBuilder, type CreateAssetHoldingIxArgs, type CreateAssetHoldingTxArgs, CreateIncentiveBuilder, type CreateIncentiveIxArgs, type CreateIncentiveTxArgs, type CreateTokenMintIxs, CreateTrancheStateBuilder, type CreateTrancheStateIxArgs, type CreateTrancheStateTxArgs, CreateVaultBuilder, type CreateVaultClientOptions, type CreateVaultIxArgs, type CreateVaultParams, type CreateVaultTxArgs, type CreateYieldPaymentParams, DEFAULT_CU_PRICE_MICRO_LAMPORTS, DEFAULT_JUNIOR_EARLY_UNSTAKE_FEE_BPS, DEFAULT_JUNIOR_STANDARD_UNSTAKE_FEE_BPS, DEFAULT_JUNIOR_WITHDRAWAL_LOCKUP_SECS, DEFAULT_MAX_ACCEPTABLE_APY_BPS, DEFAULT_MAX_ACCOUNTS, DEFAULT_MINTS, DEFAULT_MIN_AMOUNT_UI, DEFAULT_ORACLE_STALENESS_THRESHOLD_SECS, DEFAULT_PRICE_ORACLE_ACCOUNT, DEFAULT_PRICE_STALENESS_SECS, DEFAULT_PRICE_STALENESS_THRESHOLD_SECS, DEFAULT_REBALANCE_BAND_BPS, DEFAULT_SLIPPAGE_BPS, DEFAULT_TARGET_LOCAL_BPS, DEFAULT_VAULT_ID, type DecodedHolding, type DecodedVault, type DecodedVaultTrancheState, type DeleteAccountParams, DisableCircuitBreakerBuilder, type DisableCircuitBreakerIxArgs, type DisableCircuitBreakerTxArgs, DistributeIncentiveBuilder, type DistributeIncentiveIxArgs, type DistributeIncentiveTxArgs, EXTERNAL_POSITION_SAMPLES, ExecuteDepositBuilder, type ExecuteDepositIxArgs, type ExecuteDepositTxArgs, ExecuteShareSwapBuilder, type ExecuteShareSwapIxArgs, type ExecuteShareSwapTxArgs, ExecuteTrancheDepositBuilder, type ExecuteTrancheDepositIxArgs, type ExecuteTrancheDepositTxArgs, ExecuteTrancheWithdrawBuilder, type ExecuteTrancheWithdrawIxArgs, type ExecuteTrancheWithdrawTxArgs, ExecuteWithdrawBuilder, type ExecuteWithdrawIxArgs, type ExecuteWithdrawTxArgs, type ExternalLiquidityIntegrityOptions, type ExternalLiquidityIntegrityResult, ExternalLiquidityIntegrityService, type ExternalLiquidityIntegritySummary, type ExternalLiquiditySlot, type ExternalLiquiditySourceArgs, type ExternalPosition, type ExternalPositionContext, type ExternalPositionProvider, type ExternalPositionRef, ExternalPositionRegistry, FEE_VAULT_CACHE_CATEGORY, type FeeVaultAccountData, type FetchNestTokenPriceOptions, FulfillJuniorTrancheWithdrawBuilder, type FulfillJuniorTrancheWithdrawIxArgs, type FulfillJuniorTrancheWithdrawTxArgs, type FulfillSummary, type HoldingNavContribution, type HoldingUpdatePreview, IDL, IDLE_RESERVE_FLOOR_BPS, IDLE_RESERVE_TARGET_BPS, type IdleLiquidityOptions, type IdleLiquidityResult, IdleLiquidityService, type IdleLiquidityStatus, type IncentiveRecipient, type IncentiveTotals, InitializeVaultRolesBuilder, type InitializeVaultRolesIxArgs, type InitializeVaultRolesTxArgs, type JuniorWithdrawalMode, JupiterPriceSource, type JupiterPriceSourceOptions, JupiterSwapBuilder, type JupiterSwapIxArgs, type JupiterSwapTxArgs, KaminoPositionProvider, LIVE_ORACLE_VARIANTS, LIVE_PRICE_REFRESH_INTERVAL_SECS, LOCAL_PROTOCOL_ADMIN, LargeBalanceChangeError, type LargeBalanceChangeViolation, type LiveConsensusOracleDepsOptions, LivePriceSource, type LivePriceSourceOptions, MAX_BALANCE_CHANGE_BPS, MAX_CONSENSUS_SIGNERS, MAX_INCENTIVE_RECIPIENTS, MAX_MANAGER_WITHDRAW_DESTINATIONS, MAX_PRICE_STALENESS_THRESHOLD_SECS, MIN_EXTERNAL_POSITION_SAMPLES, ManagerRedepositAssetBuilder, type ManagerRedepositAssetIxArgs, type ManagerRedepositAssetTxArgs, ManagerWithdrawAssetBuilder, type ManagerWithdrawAssetIxArgs, type ManagerWithdrawAssetTxArgs, MarginfiPositionProvider, type MintConfig, type MintIdentifier, type MintInfo, MintRegistry, type MintRegistryOptions, type MockYieldAccountConfig, MockYieldTracker, type MockYieldTrackerOptions, NEST_API_BASE_URL, NEST_RWA_SHARE_MINT, NEST_VAULT_SLUG, type NavAccountBalanceResponse, type NavAccountValueResponse, type NavCrankBlocker, type NavCrankBlockerReason, type NavCrankReadiness, type NavCrankResult, type NavPriceConfig, type NavYieldAccount, NestPriceSource, type NestPriceSourceOptions, ORACLE_ENTRIES_OFFSET, ORACLE_ENTRY_SIZE, ORACLE_SETTLED_NAV_TS_OFFSET, OracleService, PRICE_ORACLE_TYPES_BY_INDEX, PROGRAM_FEE_EXEMPT_OWNER_WHITELIST, PROTOCOL_ADMIN, PROTOCOL_FEE_RECIPIENT, PdaClient, type PendingConsensusSignerSet, type PreparedDirectTransaction, type PreparedSquadsTransaction, type PreparedVaultTransaction, type PriceOracleTypeArgs, type PriceSource, ProtocolInteractionBuilder, type ProtocolInteractionIxArgs, type ProtocolInteractionTxArgs, type QuoteFeeUnit, REPORTABLE_ORACLE_VARIANTS, type RefreshLiveOraclePricesParams, RemoveAssetHoldingBuilder, type RemoveAssetHoldingIxArgs, type RemoveAssetHoldingTxArgs, RequestJuniorTrancheWithdrawBuilder, type RequestJuniorTrancheWithdrawIxArgs, type RequestJuniorTrancheWithdrawTxArgs, type ResolveExternalWithdrawArgs, type ResolvedExternalWithdraw, type ResolvedSquadsWalletRoute, type RollingLimitConfig, type RollingRebalanceLimitConfig, type RunLiveConsensusOracleOptions, type RunOptions, type RunSummary, SHARE_DECIMALS, SYSTEM_PROGRAM, SetAssetPriceOracleBuilder, type SetAssetPriceOracleIxArgs, type SetAssetPriceOracleTxArgs, SetExternalLiquidityBuilder, type SetExternalLiquidityIxArgs, type SetExternalLiquidityTxArgs, type SetIncentiveLimitsArgs, SetIncentiveLimitsBuilder, SetManagerWithdrawDestinationBuilder, type SetManagerWithdrawDestinationIxArgs, type SetManagerWithdrawDestinationTxArgs, SetProtocolFeeBuilder, type SetProtocolFeeIxArgs, type SetProtocolFeeTxArgs, SetVaultConfigBuilder, type SetVaultConfigIxArgs, type SetVaultConfigTxArgs, type SettleVaultParams, type SettleVaultResult, type SettlementSimulation, type SettlementSimulationSnapshot, type SimulateDryRunSettlementParams, type SimulateSettlementArgs, type SimulatedShareClass, SquadsProposalExecutionSimulationError, type SquadsWalletRouteConfig, type StaleBalanceChangeBypass, StaticPositionProvider, SubmitIncentiveBuilder, type SubmitIncentiveIxArgs, type SubmitIncentiveTxArgs, TOKEN_PROGRAM, TOKEN_PROGRAM_ID, type TimelockSettlementKind, type TimelockSettlementOptions, type TimelockSettlementRecord, TimelockSettlementService, type TimelockSettlementSummary, type TrackedAccountValue, type TrancheKindArgs, type TransactionBuilder, TransactionClient, USDC_MINT, USD_STAR_JUNIOR_MINT, USD_STAR_MINT, USD_STAR_PRINCIPAL_MINT, type UpdateAccountParams, UpdateAssetPriceBuilder, type UpdateAssetPriceIxArgs, type UpdateAssetPriceTxArgs, UpdateConsensusOracleBuilder, type UpdateConsensusOracleIxArgs, type UpdateConsensusOracleTxArgs, UpdateConsensusSignersBuilder, type UpdateConsensusSignersIxArgs, type UpdateConsensusSignersTxArgs, type UpdateDynamicAprParams, UpdateTrancheConfigBuilder, type UpdateTrancheConfigIxArgs, type UpdateTrancheConfigTxArgs, VAULT_CACHE_CATEGORY, VAULT_CREATOR_WHITELIST, VAULT_ENVIRONMENTS, VAULT_ORACLE_CACHE_CATEGORY, VAULT_PROGRAM_ID, VAULT_PROGRAM_IDS, VAULT_PROGRAM_PUBLIC_KEY, VAULT_ROLE_UPDATE_TIMELOCK_SECS, VAULT_TRANCHE_STATE_CACHE_CATEGORY, VAULT_TRANCHE_WITHDRAWAL_QUEUE_CACHE_CATEGORY, type Vault, type VaultAccountData, VaultBuilderBase, type VaultBuilderContext, type VaultCacheInvalidation, VaultClient, type VaultClientBundle, type VaultEnv, type VaultIncentiveAccount, type VaultIncentiveAccountData, type VaultOracleAccountData, type VaultOracleResult, type VaultPricingInputs, type VaultQuote, type VaultQuoteArgs, VaultQuoteClient, type VaultQuoteDirection, type VaultQuoteShareClass, VaultReallocationBuilder, type VaultReallocationIxArgs, type VaultReallocationTxArgs, type VaultTrancheStateAccountData, type VaultTrancheWithdrawalQueueAccountData, type VaultTransactionPlan, type WithdrawProtocolFeesIxArgs, type WithdrawProtocolFeesTxArgs, WithdrawalQueueService, type WithdrawalQueueSnapshot, type YieldAccount, type YieldAccountSnapshot, type YieldCalculationLog, type YieldCashflow, type YieldPaymentResponse, type YieldPaymentSnapshot, type YieldTracker, type YieldValuationModel, accountingUnitPriceToUsd, addCashflowUpdate, applyEffectiveApy, assertNoLargeBalanceChanges, assertNoUnconfirmedYieldPayments, buildHoldingUpdate, buildMarginfiWithdrawInteraction, buildUpdates, coerceBool, collectSamples, confirmYieldPayment, createAccount, createLiveConsensusOracleDeps, createRpcFromConnection, createTokenMint, createTokenMintIxs, createVaultClient, createYieldPayment, dateToStr, decodePendingConsensusSigners, defaultKeypairPath, deleteAccount, discoverVaultsForSigner, fetchExternalPositions, fetchNestTokenPrice, fetchReceiptMints, filterTargetHoldings, findLargeBalanceChanges, findSquadsWalletRoute, formatSettlementSimulation, fromUiAmount, gatherPricingInputs, getAccount, getAccounts, getAprYield, getBalance, getCashflows, getIncentiveRecipientShareAtas, getIncentiveRecipients, getIncentiveReportRecipients, getIncentiveTotals, getNavValue, getRpcUrl, getTotalOutstandingYield, getTotalTrackedValue, getTotalYield, getTrackedValue, getVaultProgramId, getYield, getYieldPayments, indexConfigByMint, isNavAccountBalance, isNavAccountValue, isNavYieldAccount, isVaultEnv, keypairAddress, loadKeypair, logProspectiveApy, makeProvider, mintTokensTo, mints, mostFrequent, parseExternalLiquidityRefs, planRebalance, prepareVaultTransaction, priceInAccountingUnit, readI64LE, readSplMintSupply, refreshLiveOraclePrices, resolveExternalWithdraw, resolveKeypairPath, resolveSquadsWalletRoute, resolveTrackedAmounts, roundToNextUtcMidnight, runLiveConsensusOracle, selectReportableHoldings, settleVault, signerInOracleData, simulateConsensusOracleSettlement, simulateDryRunSettlement, simulateSquadsProposalExecution, sumPositionsByMint, systemClock, toBigInt, toUiAmount, toWeb3AccountMeta, trackedValueFromResponse, updateAccount, updateDynamicApr, validateSquadsWalletRoutes, variantName, vaultAuthorityForWallet, withDiscoveredYieldAccounts };
+export { ASSET_DECIMALS, ASSET_REBALANCE_COOLDOWN_SECS, type AccountBalanceResponse, AccountClient, type AccountYieldResponse, ActivateCircuitBreakerBuilder, type ActivateCircuitBreakerIxArgs, type ActivateCircuitBreakerTxArgs, type AddAprCashflowUpdateParams, type AddCashflowUpdateParams, type AddIncentiveRecipientArgs, AddIncentiveRecipientBuilder, type AddIncentiveRecipientIxArgs, type AddNavCashflowUpdateParams, type AprAccountBalanceResponse, type AprAccountYieldResponse, type AssetPriceOracleConfigIxArgs, type AssetPriceOracleConfigTxArgs, type AssetPriceRefreshTarget, type AssetRefreshResult, type AssetType, BALANCE_CHANGE_BASELINE_MAX_AGE_SECS, type Bankineco, type BasicAuthCredentials, type Bigintish, type BuildMarginfiWithdrawInteractionArgs, CONSENSUS_ORACLE_VARIANT, type CancelIncentiveProposalArgs, CancelIncentiveProposalBuilder, CancelJuniorTrancheWithdrawBuilder, type CancelJuniorTrancheWithdrawIxArgs, type CancelJuniorTrancheWithdrawTxArgs, ClaimIncentiveBuilder, type ClaimIncentiveIxArgs, type ClaimIncentiveTxArgs, type Clock, type CollectSamplesOptions, type ConsensusAssetUpdate, type ConsensusHoldingEntry, type ConsensusHoldingSimulation, type ConsensusOracleDeps, type ConsensusOracleHoldingConfig, ConsensusOracleService, type ConsensusOracleTarget, CrankNavBuilder, type CrankNavIxArgs, type CrankNavTxArgs, CrankPerformanceFeesBuilder, type CrankPerformanceFeesIxArgs, type CrankPerformanceFeesTxArgs, type CreateAccountParams, CreateAssetHoldingBuilder, type CreateAssetHoldingIxArgs, type CreateAssetHoldingTxArgs, CreateIncentiveBuilder, type CreateIncentiveIxArgs, type CreateIncentiveTxArgs, type CreateTokenMintIxs, CreateTrancheStateBuilder, type CreateTrancheStateIxArgs, type CreateTrancheStateTxArgs, CreateVaultBuilder, type CreateVaultClientOptions, type CreateVaultIxArgs, type CreateVaultParams, type CreateVaultTxArgs, type CreateYieldPaymentParams, DEFAULT_CU_PRICE_MICRO_LAMPORTS, DEFAULT_JUNIOR_EARLY_UNSTAKE_FEE_BPS, DEFAULT_JUNIOR_STANDARD_UNSTAKE_FEE_BPS, DEFAULT_JUNIOR_WITHDRAWAL_LOCKUP_SECS, DEFAULT_MAX_ACCEPTABLE_APY_BPS, DEFAULT_MAX_ACCOUNTS, DEFAULT_MINTS, DEFAULT_MIN_AMOUNT_UI, DEFAULT_ORACLE_STALENESS_THRESHOLD_SECS, DEFAULT_PRICE_ORACLE_ACCOUNT, DEFAULT_PRICE_STALENESS_SECS, DEFAULT_PRICE_STALENESS_THRESHOLD_SECS, DEFAULT_REBALANCE_BAND_BPS, DEFAULT_SLIPPAGE_BPS, DEFAULT_TARGET_LOCAL_BPS, DEFAULT_VAULT_ID, type DecodedHolding, type DecodedVault, type DecodedVaultTrancheState, type DeleteAccountParams, DisableCircuitBreakerBuilder, type DisableCircuitBreakerIxArgs, type DisableCircuitBreakerTxArgs, DistributeIncentiveBuilder, type DistributeIncentiveIxArgs, type DistributeIncentiveTxArgs, EXTERNAL_POSITION_SAMPLES, ExecuteDepositBuilder, type ExecuteDepositIxArgs, type ExecuteDepositTxArgs, ExecuteShareSwapBuilder, type ExecuteShareSwapIxArgs, type ExecuteShareSwapTxArgs, ExecuteTrancheDepositBuilder, type ExecuteTrancheDepositIxArgs, type ExecuteTrancheDepositTxArgs, ExecuteTrancheWithdrawBuilder, type ExecuteTrancheWithdrawIxArgs, type ExecuteTrancheWithdrawTxArgs, ExecuteWithdrawBuilder, type ExecuteWithdrawIxArgs, type ExecuteWithdrawTxArgs, type ExternalLiquidityIntegrityOptions, type ExternalLiquidityIntegrityResult, ExternalLiquidityIntegrityService, type ExternalLiquidityIntegritySummary, type ExternalLiquiditySlot, type ExternalLiquiditySourceArgs, type ExternalPosition, type ExternalPositionContext, type ExternalPositionProvider, type ExternalPositionRef, ExternalPositionRegistry, FEE_VAULT_CACHE_CATEGORY, type FeeVaultAccountData, type FetchNestTokenPriceOptions, FulfillJuniorTrancheWithdrawBuilder, type FulfillJuniorTrancheWithdrawIxArgs, type FulfillJuniorTrancheWithdrawTxArgs, type FulfillSummary, type HoldingNavContribution, type HoldingUpdatePreview, IDL, IDLE_RESERVE_FLOOR_BPS, IDLE_RESERVE_TARGET_BPS, type IdleLiquidityOptions, type IdleLiquidityResult, IdleLiquidityService, type IdleLiquidityStatus, type IncentiveRecipient, type IncentiveTotals, InitializeVaultRolesBuilder, type InitializeVaultRolesIxArgs, type InitializeVaultRolesTxArgs, type JuniorWithdrawalMode, JupiterPriceSource, type JupiterPriceSourceOptions, JupiterSwapBuilder, type JupiterSwapIxArgs, type JupiterSwapTxArgs, KaminoPositionProvider, LIVE_ORACLE_VARIANTS, LIVE_PRICE_REFRESH_INTERVAL_SECS, LOCAL_PROTOCOL_ADMIN, LargeBalanceChangeError, type LargeBalanceChangeViolation, type LiveConsensusOracleDepsOptions, LivePriceSource, type LivePriceSourceOptions, MAX_APY_ANCHOR_WINDOW_SECS, MAX_BALANCE_CHANGE_BPS, MAX_CONSENSUS_SIGNERS, MAX_INCENTIVE_RECIPIENTS, MAX_MANAGER_WITHDRAW_DESTINATIONS, MAX_PRICE_STALENESS_THRESHOLD_SECS, MIN_EXTERNAL_POSITION_SAMPLES, ManagerRedepositAssetBuilder, type ManagerRedepositAssetIxArgs, type ManagerRedepositAssetTxArgs, ManagerWithdrawAssetBuilder, type ManagerWithdrawAssetIxArgs, type ManagerWithdrawAssetTxArgs, MarginfiPositionProvider, type MaxApyAnchorSnapshot, type MintConfig, type MintIdentifier, type MintInfo, MintRegistry, type MintRegistryOptions, type MockYieldAccountConfig, MockYieldTracker, type MockYieldTrackerOptions, NEST_API_BASE_URL, NEST_RWA_SHARE_MINT, NEST_VAULT_SLUG, type NavAccountBalanceResponse, type NavAccountValueResponse, type NavCrankBlocker, type NavCrankBlockerReason, type NavCrankReadiness, type NavCrankResult, type NavPriceConfig, type NavYieldAccount, NestPriceSource, type NestPriceSourceOptions, ORACLE_ENTRIES_OFFSET, ORACLE_ENTRY_SIZE, ORACLE_SETTLED_NAV_TS_OFFSET, OracleService, PRICE_ORACLE_TYPES_BY_INDEX, PROGRAM_FEE_EXEMPT_OWNER_WHITELIST, PROTOCOL_ADMIN, PROTOCOL_FEE_RECIPIENT, PdaClient, type PendingConsensusSignerSet, type PreparedDirectTransaction, type PreparedSquadsTransaction, type PreparedVaultTransaction, type PriceOracleTypeArgs, type PriceSource, ProtocolInteractionBuilder, type ProtocolInteractionIxArgs, type ProtocolInteractionTxArgs, type QuoteFeeUnit, REPORTABLE_ORACLE_VARIANTS, type RealizedApySimulation, type RefreshLiveOraclePricesParams, RemoveAssetHoldingBuilder, type RemoveAssetHoldingIxArgs, type RemoveAssetHoldingTxArgs, RequestJuniorTrancheWithdrawBuilder, type RequestJuniorTrancheWithdrawIxArgs, type RequestJuniorTrancheWithdrawTxArgs, type ResolveExternalWithdrawArgs, type ResolvedExternalWithdraw, type ResolvedSquadsWalletRoute, type RollingLimitConfig, type RollingRebalanceLimitConfig, type RunLiveConsensusOracleOptions, type RunOptions, type RunSummary, SHARE_DECIMALS, SYSTEM_PROGRAM, SetAssetPriceOracleBuilder, type SetAssetPriceOracleIxArgs, type SetAssetPriceOracleTxArgs, SetExternalLiquidityBuilder, type SetExternalLiquidityIxArgs, type SetExternalLiquidityTxArgs, type SetIncentiveLimitsArgs, SetIncentiveLimitsBuilder, SetManagerWithdrawDestinationBuilder, type SetManagerWithdrawDestinationIxArgs, type SetManagerWithdrawDestinationTxArgs, SetProtocolFeeBuilder, type SetProtocolFeeIxArgs, type SetProtocolFeeTxArgs, SetVaultConfigBuilder, type SetVaultConfigIxArgs, type SetVaultConfigTxArgs, type SettleVaultParams, type SettleVaultResult, type SettlementSimulation, type SettlementSimulationSnapshot, type SimulateDryRunSettlementParams, type SimulateSettlementArgs, type SimulatedShareClass, SquadsProposalExecutionSimulationError, type SquadsWalletRouteConfig, type StaleBalanceChangeBypass, StaticPositionProvider, SubmitIncentiveBuilder, type SubmitIncentiveIxArgs, type SubmitIncentiveTxArgs, TOKEN_PROGRAM, TOKEN_PROGRAM_ID, type TimelockSettlementKind, type TimelockSettlementOptions, type TimelockSettlementRecord, TimelockSettlementService, type TimelockSettlementSummary, type TrackedAccountValue, type TrancheKindArgs, type TransactionBuilder, TransactionClient, USDC_MINT, USD_STAR_JUNIOR_MINT, USD_STAR_MINT, USD_STAR_PRINCIPAL_MINT, type UpdateAccountParams, UpdateAssetPriceBuilder, type UpdateAssetPriceIxArgs, type UpdateAssetPriceTxArgs, UpdateConsensusOracleBuilder, type UpdateConsensusOracleIxArgs, type UpdateConsensusOracleTxArgs, UpdateConsensusSignersBuilder, type UpdateConsensusSignersIxArgs, type UpdateConsensusSignersTxArgs, type UpdateDynamicAprParams, UpdateTrancheConfigBuilder, type UpdateTrancheConfigIxArgs, type UpdateTrancheConfigTxArgs, VAULT_CACHE_CATEGORY, VAULT_CREATOR_WHITELIST, VAULT_ENVIRONMENTS, VAULT_ORACLE_CACHE_CATEGORY, VAULT_PROGRAM_ID, VAULT_PROGRAM_IDS, VAULT_PROGRAM_PUBLIC_KEY, VAULT_ROLE_UPDATE_TIMELOCK_SECS, VAULT_TRANCHE_STATE_CACHE_CATEGORY, VAULT_TRANCHE_WITHDRAWAL_QUEUE_CACHE_CATEGORY, type Vault, type VaultAccountData, VaultBuilderBase, type VaultBuilderContext, type VaultCacheInvalidation, VaultClient, type VaultClientBundle, type VaultEnv, type VaultIncentiveAccount, type VaultIncentiveAccountData, type VaultOracleAccountData, type VaultOracleResult, type VaultPricingInputs, type VaultQuote, type VaultQuoteArgs, VaultQuoteClient, type VaultQuoteDirection, type VaultQuoteShareClass, VaultReallocationBuilder, type VaultReallocationIxArgs, type VaultReallocationTxArgs, type VaultTrancheStateAccountData, type VaultTrancheWithdrawalQueueAccountData, type VaultTransactionPlan, type WithdrawProtocolFeesIxArgs, type WithdrawProtocolFeesTxArgs, WithdrawalQueueService, type WithdrawalQueueSnapshot, type YieldAccount, type YieldAccountSnapshot, type YieldCalculationLog, type YieldCashflow, type YieldPaymentResponse, type YieldPaymentSnapshot, type YieldTracker, type YieldValuationModel, accountingUnitPriceToUsd, addCashflowUpdate, applyEffectiveApy, assertNoLargeBalanceChanges, assertNoUnconfirmedYieldPayments, buildHoldingUpdate, buildMarginfiWithdrawInteraction, buildUpdates, coerceBool, collectSamples, confirmYieldPayment, createAccount, createLiveConsensusOracleDeps, createRpcFromConnection, createTokenMint, createTokenMintIxs, createVaultClient, createYieldPayment, dateToStr, decodePendingConsensusSigners, defaultKeypairPath, deleteAccount, discoverVaultsForSigner, fetchExternalPositions, fetchNestTokenPrice, fetchReceiptMints, filterTargetHoldings, findLargeBalanceChanges, findSquadsWalletRoute, formatSettlementSimulation, fromUiAmount, gatherPricingInputs, getAccount, getAccounts, getAprYield, getBalance, getCashflows, getIncentiveRecipientShareAtas, getIncentiveRecipients, getIncentiveReportRecipients, getIncentiveTotals, getNavValue, getRpcUrl, getTotalOutstandingYield, getTotalTrackedValue, getTotalYield, getTrackedValue, getVaultProgramId, getYield, getYieldPayments, indexConfigByMint, isNavAccountBalance, isNavAccountValue, isNavYieldAccount, isVaultEnv, keypairAddress, loadKeypair, logProspectiveApy, makeProvider, mintTokensTo, mints, mostFrequent, parseExternalLiquidityRefs, planRebalance, prepareVaultTransaction, priceInAccountingUnit, readI64LE, readSplMintSupply, refreshLiveOraclePrices, resolveExternalWithdraw, resolveKeypairPath, resolveSquadsWalletRoute, resolveTrackedAmounts, roundToNextUtcMidnight, runLiveConsensusOracle, selectReportableHoldings, settleVault, signerInOracleData, simulateConsensusOracleSettlement, simulateDryRunSettlement, simulateSquadsProposalExecution, sumPositionsByMint, systemClock, toBigInt, toUiAmount, toWeb3AccountMeta, trackedValueFromResponse, updateAccount, updateDynamicApr, validateSquadsWalletRoutes, variantName, vaultAuthorityForWallet, withDiscoveredYieldAccounts };

package/dist/index.js

@@ -3249,6 +3249,7 @@ __export(index_exports, {
   LOCAL_PROTOCOL_ADMIN: () => LOCAL_PROTOCOL_ADMIN,
   LargeBalanceChangeError: () => LargeBalanceChangeError,
   LivePriceSource: () => LivePriceSource,
+  MAX_APY_ANCHOR_WINDOW_SECS: () => MAX_APY_ANCHOR_WINDOW_SECS,
   MAX_BALANCE_CHANGE_BPS: () => MAX_BALANCE_CHANGE_BPS,
   MAX_CONSENSUS_SIGNERS: () => MAX_CONSENSUS_SIGNERS,
   MAX_INCENTIVE_RECIPIENTS: () => MAX_INCENTIVE_RECIPIENTS,
@@ -9916,8 +9917,9 @@ var IDL = {
           {
             name: "max_apy_bps",
             docs: [
-              "Maximum annualized APY accepted between oracle NAV updates that advance",
-              "the vault's regular performance-fee high-water mark, in basis points."
+              "Maximum linear annualized growth of the settled regular share price",
+              "against `max_apy_anchor`, for settlements advancing its performance-fee",
+              "high-water mark. Basis points; zero disables enforcement, not observation."
             ],
             type: "u16"
           },
@@ -9964,10 +9966,23 @@ var IDL = {
             ],
             type: "i64"
           },
+          {
+            name: "max_apy_anchor",
+            docs: [
+              "Independent of the durable fixed-APY accrual anchor above. Carved from",
+              "reserved bytes without changing APYConfig or Vault size/field offsets.",
+              "Existing zero-filled accounts initialize lazily from a known price/time."
+            ],
+            type: {
+              defined: {
+                name: "MaxApyAnchor"
+              }
+            }
+          },
           {
             name: "_padding1",
             type: {
-              array: ["u64", 32]
+              array: ["u64", 28]
             }
           }
         ]
@@ -10554,6 +10569,41 @@ var IDL = {
         ]
       }
     },
+    {
+      name: "MaxApyAnchor",
+      docs: [
+        "Weekly observations of the settled regular share price. Keep the previous",
+        "observation while the newest is younger than seven days, so rollover never",
+        "reduces a mature comparison window to a few seconds. With regular settlement",
+        "the effective lookback is seven to fourteen days; sparse settlement can make",
+        "it longer. A new cohort uses its actual age until seven days of history exist."
+      ],
+      serialization: "bytemuck",
+      repr: {
+        kind: "c"
+      },
+      type: {
+        kind: "struct",
+        fields: [
+          {
+            name: "share_price",
+            type: "u64"
+          },
+          {
+            name: "timestamp",
+            type: "i64"
+          },
+          {
+            name: "previous_share_price",
+            type: "u64"
+          },
+          {
+            name: "previous_timestamp",
+            type: "i64"
+          }
+        ]
+      }
+    },
     {
       name: "PendingManagerWithdrawDestination",
       docs: [
@@ -17796,6 +17846,7 @@ var DEFAULT_SHARE_PRICE = 1000000n;
 var BPS_DENOMINATOR3 = 10000n;
 var NAV_LOSS_TOLERANCE_BPS = 25n;
 var SECONDS_PER_YEAR = 31536000n;
+var MAX_APY_ANCHOR_WINDOW_SECS = 604800n;
 var DEFAULT_STALENESS_SECS = 86400n;
 var CONSENSUS_MAX_DIFF_BPS = 8n;
 var MIN_CONSENSUS_SIGNERS = 2;
@@ -17898,6 +17949,7 @@ function simulateConsensusOracleSettlement(args) {
       current
     };
   }
+  let realizedApy;
   try {
     const settlement = settleVault({
       grossNav,
@@ -17916,7 +17968,11 @@ function simulateConsensusOracleSettlement(args) {
       accruedApyBalance: bigint(apyConfig.accruedApyBalance),
       apyAnchorSharePrice: bigint(apyConfig.anchorSharePrice),
       apyAnchorTs: bigint(apyConfig.anchorTs),
-      tranche: currentTranche
+      maxApyAnchor: decodeMaxApyAnchor(apyConfig.maxApyAnchor),
+      tranche: currentTranche,
+      onRealizedApy: (diagnostic) => {
+        realizedApy = diagnostic;
+      }
     });
     return {
       nowTs: args.nowTs,
@@ -17928,6 +17984,8 @@ function simulateConsensusOracleSettlement(args) {
       consensus,
       navContributions,
       grossNav,
+      realizedApy,
+      projectedMaxApyAnchor: settlement.maxApyAnchor,
       settledAccountingNav: settlement.settledAccountingNav,
       current,
       projected: settlement.projected,
@@ -17955,6 +18013,8 @@ function simulateConsensusOracleSettlement(args) {
       });
       return {
         ...projection,
+        // Retain the real configured cap when the projection retries uncapped.
+        realizedApy: realizedApy ?? projection.realizedApy,
         canSettle: false,
         blockers: [...blockers, ...projection.blockers],
         projectionRequiresLossesEnabled: projection.projected ? requiresLossesEnabled || projection.projectionRequiresLossesEnabled : void 0,
@@ -17971,6 +18031,7 @@ function simulateConsensusOracleSettlement(args) {
       consensus,
       navContributions,
       grossNav,
+      realizedApy,
       current
     };
   }
@@ -18045,8 +18106,23 @@ function settleVault(args) {
       `crank would fail LossesDisabled: gross NAV ${args.grossNav} is more than ${NAV_LOSS_TOLERANCE_BPS}bps below physical NAV ${physicalNavBefore}`
     );
   }
-  const priorTs = args.priorSettledNavTs > 0n ? args.priorSettledNavTs : max(args.accountingLastUpdateTs, args.apyAnchorTs);
-  const nextApyValue = args.tranche ? args.grossNav : sharePriceForValue(args.grossNav, args.totalSupply);
+  const priorSettledTs = args.priorSettledNavTs > 0n ? args.priorSettledNavTs : max(args.accountingLastUpdateTs, args.apyAnchorTs);
+  let maxApyAnchor = { ...args.maxApyAnchor };
+  let timestampSource = "apy.max_apy_anchor.timestamp";
+  if (maxApyAnchor.sharePrice <= 0n || maxApyAnchor.timestamp <= 0n) {
+    const hasFixedAnchor = args.apyAnchorSharePrice > 0n && args.apyAnchorTs > 0n;
+    maxApyAnchor = {
+      sharePrice: hasFixedAnchor ? args.apyAnchorSharePrice : args.currentSharePrice,
+      timestamp: hasFixedAnchor ? args.apyAnchorTs : max(priorSettledTs, args.accountingLastUpdateTs),
+      previousSharePrice: 0n,
+      previousTimestamp: 0n
+    };
+    timestampSource = hasFixedAnchor ? "legacy fixed-APY anchor (initialization)" : "current share-price observation (initialization)";
+  }
+  const usePrevious = args.nowTs - maxApyAnchor.timestamp < MAX_APY_ANCHOR_WINDOW_SECS && maxApyAnchor.previousSharePrice > 0n && maxApyAnchor.previousTimestamp > 0n;
+  const priorApyValue = usePrevious ? maxApyAnchor.previousSharePrice : maxApyAnchor.sharePrice;
+  const priorTs = usePrevious ? maxApyAnchor.previousTimestamp : maxApyAnchor.timestamp;
+  if (usePrevious) timestampSource = "apy.max_apy_anchor.previous_timestamp";
   let regularValue;
   let regularSharePrice = args.currentSharePrice;
   let regularHwmSharePrice = args.hwmSharePrice;
@@ -18119,15 +18195,55 @@ function settleVault(args) {
     curatorFee = regularFees.fees.curator;
     protocolFee = regularFees.fees.protocol;
   }
+  const nextApyValue = args.totalSupply > 0n ? regularSharePrice : void 0;
+  const elapsedSecs = args.nowTs - priorTs;
+  const numerator = nextApyValue === void 0 ? void 0 : (nextApyValue - priorApyValue) * BPS_DENOMINATOR3 * SECONDS_PER_YEAR;
+  const denominator = priorApyValue * elapsedSecs;
+  const rateAvailable = numerator !== void 0 && priorApyValue > 0n && priorTs > 0n && elapsedSecs > 0n;
+  args.onRealizedApy({
+    basis: "regular-share-price",
+    priorValue: priorApyValue,
+    nextValue: nextApyValue,
+    priorTs,
+    timestampSource,
+    checkpointTs: maxApyAnchor.timestamp,
+    nowTs: args.nowTs,
+    elapsedSecs,
+    impliedApyMicroBps: rateAvailable ? numerator * 1000000n / denominator : void 0,
+    minimumCapBps: rateAvailable ? numerator > 0n ? (numerator + denominator - 1n) / denominator : 0n : void 0,
+    maxApyBps: args.maxApyBps,
+    fixedApyBps: args.fixedApyBps,
+    hwmBefore: args.hwmSharePrice,
+    hwmAfter: regularHwmSharePrice
+  });
   if (regularHwmSharePrice > args.hwmSharePrice && nextApyValue !== void 0) {
     validateRealizedApy(
-      args.tranche ? physicalNavBefore : args.currentSharePrice,
+      priorApyValue,
       priorTs,
       nextApyValue,
       args.nowTs,
       args.maxApyBps
     );
   }
+  if (args.totalSupply > 0n) {
+    if (maxApyAnchor.sharePrice <= 0n || maxApyAnchor.timestamp <= 0n) {
+      maxApyAnchor = {
+        sharePrice: regularSharePrice,
+        timestamp: args.nowTs,
+        previousSharePrice: 0n,
+        previousTimestamp: 0n
+      };
+    } else if (args.nowTs - maxApyAnchor.timestamp >= MAX_APY_ANCHOR_WINDOW_SECS) {
+      maxApyAnchor = {
+        sharePrice: regularSharePrice,
+        timestamp: args.nowTs,
+        previousSharePrice: maxApyAnchor.sharePrice,
+        previousTimestamp: maxApyAnchor.timestamp
+      };
+    }
+  } else {
+    maxApyAnchor = args.maxApyAnchor;
+  }
   const totalFees = curatorFee + protocolFee;
   const netRegularBacking = mulDiv2(
     args.totalSupply,
@@ -18154,6 +18270,7 @@ function settleVault(args) {
   return {
     settledAccountingNav,
     projected,
+    maxApyAnchor,
     performanceFees: {
       curator: curatorFee,
       protocol: protocolFee,
@@ -18162,6 +18279,15 @@ function settleVault(args) {
     }
   };
 }
+function decodeMaxApyAnchor(value) {
+  const decoded = record(value);
+  return {
+    sharePrice: bigint(decoded.sharePrice),
+    timestamp: bigint(decoded.timestamp),
+    previousSharePrice: bigint(decoded.previousSharePrice),
+    previousTimestamp: bigint(decoded.previousTimestamp)
+  };
+}
 function settleTrancheNav(tranche, currentTvl, nextTvl, nowTs) {
   const before = tranche.junior.value + tranche.senior.value;
   if (before === 0n) {
@@ -18343,7 +18469,7 @@ function validateRealizedApy(priorValue, priorTs, nextValue, nextTs, maxApyBps)
   const lhs = (nextValue - priorValue) * BPS_DENOMINATOR3 * SECONDS_PER_YEAR;
   const rhs = BigInt(maxApyBps) * priorValue * elapsed;
   if (lhs > rhs) {
-    const implied = lhs / (priorValue * elapsed);
+    const implied = formatUnits(lhs * 1000000n / (priorValue * elapsed), 6);
     throw new Error(
       `crank would fail MaxApyExceeded: implied ${implied}bps > ${maxApyBps}bps`
     );
@@ -18700,6 +18826,13 @@ function formatSettlementSimulation(simulation) {
   lines.push(
     `  crank simulation: ${simulation.canSettle ? "WOULD SETTLE" : "BLOCKED"}`
   );
+  if (simulation.realizedApy) {
+    lines.push(...formatRealizedApy(simulation.realizedApy));
+  } else {
+    lines.push(
+      "    max-APY diagnostic unavailable: settlement did not reach the APY check"
+    );
+  }
   for (const holding of simulation.consensus) {
     const detail = holding.settledPrice ? `price=${holding.settledPrice} external=${holding.settledExternalAmount}` : holding.reason ?? "no aggregate";
     lines.push(
@@ -18821,6 +18954,70 @@ function formatSettlementSimulation(simulation) {
     lines.push(`    warning: ${warning}`);
   return lines;
 }
+function formatRealizedApy(apy) {
+  const lines = [
+    `    max-APY share-price anchor -> settled regular share price (after tranche allocation, fixed APY, and fees): ${formatUnits(
+      apy.priorValue,
+      6
+    )} [${apy.priorValue}] -> ${apy.nextValue === void 0 ? "unavailable (zero supply)" : `${formatUnits(apy.nextValue, 6)} [${apy.nextValue}]`}`,
+    `      weekly checkpoints: every 604800s (7 days); previous checkpoint retained through rollover; latest=${apy.checkpointTs}`,
+    `      observation window: ${formatUnits(
+      apy.elapsedSecs * 1000000n / 86400n,
+      6
+    )} days${apy.elapsedSecs < MAX_APY_ANCHOR_WINDOW_SECS ? " (initial history is shorter than 7 days)" : ""}`,
+    `      timestamp: ${apy.priorTs} from ${apy.timestampSource}; settlement time estimate=${apy.nowTs}; elapsed=${apy.elapsedSecs}s`,
+    `      configured max: ${apy.maxApyBps}bps (${formatUnits(
+      BigInt(apy.maxApyBps),
+      2
+    )}%); regular HWM: ${apy.hwmBefore} -> ${apy.hwmAfter}`
+  ];
+  if (apy.impliedApyMicroBps !== void 0) {
+    lines.push(
+      `      implied APY (linear annualization): ${formatUnits(
+        apy.impliedApyMicroBps,
+        6
+      )}bps (${formatUnits(apy.impliedApyMicroBps, 8)}%)`
+    );
+    lines.push(
+      "      formula: (new - anchor) * 10,000 * 31,536,000 / (anchor * elapsed_seconds)"
+    );
+  } else {
+    lines.push(
+      "      implied APY: unavailable (missing baseline/supply or non-positive elapsed time)"
+    );
+  }
+  const hwmAdvances = apy.hwmAfter > apy.hwmBefore;
+  const positiveGrowth = apy.nextValue !== void 0 && apy.nextValue > apy.priorValue;
+  const comparisonApplies = hwmAdvances && positiveGrowth && apy.priorValue > 0n && apy.priorTs > 0n;
+  const status = apy.maxApyBps === 0 ? "DISABLED (0 means uncapped)" : !hwmAdvances ? "BYPASSED (regular HWM does not advance)" : apy.nextValue === void 0 ? "BYPASSED (zero regular supply)" : apy.priorValue === 0n || apy.priorTs <= 0n ? "BYPASSED (no valid prior anchor)" : !positiveGrowth ? "BYPASSED (no positive growth)" : apy.elapsedSecs <= 0n ? "BLOCKED (positive growth with no elapsed time; no nonzero cap passes)" : apy.minimumCapBps > BigInt(apy.maxApyBps) ? "BLOCKED (MaxApyExceeded)" : "PASS";
+  lines.push(`      max-APY guard: ${status}`);
+  if (comparisonApplies && apy.elapsedSecs > 0n && apy.minimumCapBps !== void 0) {
+    const minimum = max(1n, max(apy.minimumCapBps, BigInt(apy.fixedApyBps)));
+    lines.push(
+      `      minimum nonzero --max-apy-bps for this snapshot: ${minimum} (${formatUnits(
+        minimum,
+        2
+      )}%; rounded UP, includes fixed-APY config floor)`
+    );
+    if (minimum > BPS_DENOMINATOR3) {
+      lines.push(
+        "      exceeds the configurable maximum of 10000bps (100%); no supported nonzero cap passes this snapshot"
+      );
+    }
+  } else if (comparisonApplies && apy.elapsedSecs <= 0n) {
+    lines.push(
+      "      no nonzero cap passes positive growth until settlement time advances beyond the anchor"
+    );
+  } else if (!comparisonApplies) {
+    lines.push(
+      "      this settlement does not require a higher cap; the HWM/baseline/growth gate bypasses the comparison"
+    );
+  }
+  lines.push(
+    "      estimate uses current consensus and sampled time; later reports or settlement time can change it"
+  );
+  return lines;
+}
 function formatTransition(before, after, decimals) {
   return `${formatUnits(before, decimals)} [${before}] -> ${formatUnits(
     after,
@@ -19042,12 +19239,7 @@ async function gatherPricingInputs(deps, target, vaultState, reportableHoldings,
       `no USD price for base asset ${baseMint} (cannot denominate prices)`
     );
   }
-  const lpByMint = await fetchExternalPositions(
-    deps,
-    target,
-    vaultState,
-    log
-  );
+  const lpByMint = await fetchExternalPositions(deps, target, vaultState, log);
   return {
     assetDecimals: vaultState.config.assetDecimals,
     baseUsd,
@@ -19231,14 +19423,6 @@ async function settleVault2({
       `  holding #${update.holdingIndex} ${update.mint}: price=${update.price} external_amount=${update.externalAmount} [lp=${update.lpAmount} tracked=${update.trackedValueAmount} principal=${update.trackedPrincipalAmount} yield=${update.yieldAmount}]`
     );
   }
-  await logProspectiveApy({
-    client,
-    vault,
-    updates,
-    vaultState,
-    nowSecs,
-    log
-  });
   try {
     const simulation = await simulateDryRunSettlement({
       client,
@@ -19321,7 +19505,7 @@ async function logProspectiveApy({
     if (elapsedSecs <= 0n) return;
     const apyBps = (prospectiveNav - physicalNavBefore) * SECONDS_PER_YEAR2 * 10000n / (physicalNavBefore * elapsedSecs);
     log(
-      `vault ${vault}: prospective NAV ${prospectiveNav} vs physical baseline ${physicalNavBefore} (elapsed ${elapsedSecs}s) \u2192 implied APY ${apyBps}bps`
+      `vault ${vault}: raw candidate estimate (before consensus, not the max-APY check): NAV ${prospectiveNav} vs physical baseline ${physicalNavBefore} (elapsed ${elapsedSecs}s) \u2192 implied APY ${apyBps}bps`
     );
   } catch {
   }
@@ -21024,6 +21208,7 @@ var import_common56 = __toESM(require_dist());
   LOCAL_PROTOCOL_ADMIN,
   LargeBalanceChangeError,
   LivePriceSource,
+  MAX_APY_ANCHOR_WINDOW_SECS,
   MAX_BALANCE_CHANGE_BPS,
   MAX_CONSENSUS_SIGNERS,
   MAX_INCENTIVE_RECIPIENTS,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@perena/vault-sdk",
-  "version": "1.0.42",
+  "version": "1.0.44",
   "description": "Vault program helpers for Bankineco integrations.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",