@drift-labs/vaults-sdk 0.4.32 → 0.4.33

package/lib/constants/index.d.ts

@@ -1,2 +1,5 @@
 import { BN } from '@drift-labs/sdk';
 export declare const VAULT_SHARES_PRECISION_EXP: BN;
+export declare const FUEL_SHARE_PRECISION_EXP: BN;
+export declare const FUEL_SHARE_PRECISION: BN;
+export declare const MAGIC_FUEL_START_TS = 123;

package/lib/constants/index.js

@@ -1,5 +1,10 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.VAULT_SHARES_PRECISION_EXP = void 0;
+exports.MAGIC_FUEL_START_TS = exports.FUEL_SHARE_PRECISION = exports.FUEL_SHARE_PRECISION_EXP = exports.VAULT_SHARES_PRECISION_EXP = void 0;
 const sdk_1 = require("@drift-labs/sdk");
 exports.VAULT_SHARES_PRECISION_EXP = new sdk_1.BN(6);
+// arbitrarily large fuel per share precision
+exports.FUEL_SHARE_PRECISION_EXP = new sdk_1.BN(18);
+exports.FUEL_SHARE_PRECISION = sdk_1.TEN.pow(exports.FUEL_SHARE_PRECISION_EXP);
+// some arbitrary timestamp to identify VaultDepositors created after fuel distribution started.
+exports.MAGIC_FUEL_START_TS = 123;

package/lib/math/vaultDepositor.d.ts

@@ -1,4 +1,4 @@
-import { BN } from '@drift-labs/sdk';
+import { BN, FuelOverflowAccount, UserStatsAccount } from '@drift-labs/sdk';
 import { Vault, VaultDepositor, VaultProtocol } from '../types/types';
 /**
  * Calculates the unrealized profitShare for a vaultDepositor
@@ -21,3 +21,6 @@ export declare function calculateProfitShare(vaultDepositor: VaultDepositor, tot
  * @returns
  */
 export declare function calculateRealizedVaultDepositorEquity(vaultDepositor: VaultDepositor, vaultEquity: BN, vault: Vault, vaultProtocol?: VaultProtocol): BN;
+export declare function calculateVaultUnsettledFuelPerShare(vault: Vault, vaultUserStats: UserStatsAccount, fuelOverflow?: FuelOverflowAccount): BN;
+export declare function calculateVaultDepositorUnsettledFuel(vaultDepositor: VaultDepositor, vault: Vault, vaultUserStats: UserStatsAccount, fuelOverflow?: FuelOverflowAccount): BN;
+export declare function calculateVaultDepositorFuel(vaultDepositor: VaultDepositor, vault: Vault, vaultUserStats: UserStatsAccount, fuelOverflow?: FuelOverflowAccount): BN;

package/lib/math/vaultDepositor.js

@@ -3,7 +3,12 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.calculateApplyProfitShare = calculateApplyProfitShare;
 exports.calculateProfitShare = calculateProfitShare;
 exports.calculateRealizedVaultDepositorEquity = calculateRealizedVaultDepositorEquity;
+exports.calculateVaultUnsettledFuelPerShare = calculateVaultUnsettledFuelPerShare;
+exports.calculateVaultDepositorUnsettledFuel = calculateVaultDepositorUnsettledFuel;
+exports.calculateVaultDepositorFuel = calculateVaultDepositorFuel;
 const sdk_1 = require("@drift-labs/sdk");
+const types_1 = require("../types/types");
+const constants_1 = require("../constants");
 /**
  * Calculates the unrealized profitShare for a vaultDepositor
  * @param vaultDepositor
@@ -47,3 +52,73 @@ function calculateRealizedVaultDepositorEquity(vaultDepositor, vaultEquity, vaul
     const profitShareAmount = calculateProfitShare(vaultDepositor, vdAmount, vault, vaultProtocol);
     return vdAmount.sub(profitShareAmount);
 }
+function calculateVaultUnsettledFuelPerShare(vault, vaultUserStats, fuelOverflow) {
+    if ((vaultUserStats.fuelOverflowStatus & sdk_1.FuelOverflowStatus.Exists) === 1 &&
+        !fuelOverflow) {
+        throw new Error('UserStats requires a FuelOverflow account to calculate total fuel');
+    }
+    const userStatsTotalFuel = new sdk_1.BN(vaultUserStats.fuelInsurance)
+        .add(new sdk_1.BN(vaultUserStats.fuelDeposits))
+        .add(new sdk_1.BN(vaultUserStats.fuelBorrows))
+        .add(new sdk_1.BN(vaultUserStats.fuelPositions))
+        .add(new sdk_1.BN(vaultUserStats.fuelTaker))
+        .add(new sdk_1.BN(vaultUserStats.fuelMaker));
+    const overflowFuel = fuelOverflow
+        ? new sdk_1.BN(fuelOverflow.fuelInsurance)
+            .add(fuelOverflow.fuelDeposits)
+            .add(fuelOverflow.fuelBorrows)
+            .add(fuelOverflow.fuelPositions)
+            .add(fuelOverflow.fuelTaker)
+            .add(fuelOverflow.fuelMaker)
+        : sdk_1.ZERO;
+    const totalFuel = userStatsTotalFuel.add(overflowFuel);
+    if (totalFuel > vault.cumulativeFuel) {
+        let shareDenominator = vault.userShares;
+        if (vault.fuelDistributionMode === types_1.FuelDistributionMode.UsersOnly) {
+            if (vault.userShares.eq(sdk_1.ZERO)) {
+                shareDenominator = vault.totalShares;
+            }
+            else {
+                shareDenominator = vault.userShares;
+            }
+        }
+        else if (vault.fuelDistributionMode === types_1.FuelDistributionMode.UsersAndManager) {
+            shareDenominator = vault.totalShares;
+        }
+        if (shareDenominator.gt(sdk_1.ZERO)) {
+            const fuelDelta = totalFuel.sub(vault.cumulativeFuel);
+            const fuelDeltaPerShare = fuelDelta
+                .mul(constants_1.FUEL_SHARE_PRECISION)
+                .div(shareDenominator);
+            return vault.cumulativeFuelPerShare.add(fuelDeltaPerShare);
+        }
+    }
+    return vault.cumulativeFuelPerShare;
+}
+function calculateVaultDepositorUnsettledFuel(vaultDepositor, vault, vaultUserStats, fuelOverflow) {
+    // If timestamp hasn't changed, no new fuel to calculate
+    if (Date.now() / 1000 <= vaultDepositor.lastFuelUpdateTs) {
+        return vaultDepositor.fuelAmount;
+    }
+    // Special case for initial fuel setup
+    if (vaultDepositor.lastFuelUpdateTs === constants_1.MAGIC_FUEL_START_TS) {
+        return vaultDepositor.fuelAmount;
+    }
+    const cumulativeFuelPerShare = calculateVaultUnsettledFuelPerShare(vault, vaultUserStats, fuelOverflow);
+    // If vault's cumulative fuel per share is less than depositor's recorded amount,
+    // this means the vault's fuel was reset - no new fuel to add
+    if (cumulativeFuelPerShare.lt(vaultDepositor.cumulativeFuelPerShareAmount)) {
+        return vaultDepositor.fuelAmount;
+    }
+    // Calculate new fuel
+    const fuelPerShareDelta = cumulativeFuelPerShare.sub(vaultDepositor.cumulativeFuelPerShareAmount);
+    const newFuel = fuelPerShareDelta
+        .mul(vaultDepositor.vaultShares)
+        .div(constants_1.FUEL_SHARE_PRECISION);
+    return vaultDepositor.fuelAmount.add(newFuel);
+}
+function calculateVaultDepositorFuel(vaultDepositor, vault, vaultUserStats, fuelOverflow) {
+    const vdFuel = vaultDepositor.fuelAmount;
+    const unsettledFuel = calculateVaultDepositorUnsettledFuel(vaultDepositor, vault, vaultUserStats, fuelOverflow);
+    return vdFuel.add(unsettledFuel);
+}

package/lib/types/drift_vaults.d.ts

@@ -1,5 +1,5 @@
 export type DriftVaults = {
-    version: '0.2.0';
+    version: '0.4.0';
     name: 'drift_vaults';
     instructions: [
         {
@@ -276,6 +276,32 @@ export type DriftVaults = {
                 }
             ];
         },
+        {
+            name: 'updateCumulativeFuelAmount';
+            accounts: [
+                {
+                    name: 'vault';
+                    isMut: true;
+                    isSigner: false;
+                },
+                {
+                    name: 'vaultDepositor';
+                    isMut: true;
+                    isSigner: false;
+                },
+                {
+                    name: 'signer';
+                    isMut: false;
+                    isSigner: true;
+                },
+                {
+                    name: 'driftUserStats';
+                    isMut: true;
+                    isSigner: false;
+                }
+            ];
+            args: [];
+        },
         {
             name: 'initializeVaultDepositor';
             accounts: [
@@ -745,6 +771,58 @@ export type DriftVaults = {
             ];
             args: [];
         },
+        {
+            name: 'resetFuelSeason';
+            accounts: [
+                {
+                    name: 'vault';
+                    isMut: true;
+                    isSigner: false;
+                },
+                {
+                    name: 'vaultDepositor';
+                    isMut: true;
+                    isSigner: false;
+                },
+                {
+                    name: 'admin';
+                    isMut: false;
+                    isSigner: true;
+                },
+                {
+                    name: 'driftUserStats';
+                    isMut: true;
+                    isSigner: false;
+                },
+                {
+                    name: 'driftState';
+                    isMut: false;
+                    isSigner: false;
+                }
+            ];
+            args: [];
+        },
+        {
+            name: 'resetVaultFuelSeason';
+            accounts: [
+                {
+                    name: 'vault';
+                    isMut: true;
+                    isSigner: false;
+                },
+                {
+                    name: 'admin';
+                    isMut: false;
+                    isSigner: true;
+                },
+                {
+                    name: 'driftState';
+                    isMut: false;
+                    isSigner: false;
+                }
+            ];
+            args: [];
+        },
         {
             name: 'managerDeposit';
             accounts: [
@@ -930,6 +1008,27 @@ export type DriftVaults = {
             ];
             args: [];
         },
+        {
+            name: 'managerUpdateFuelDistributionMode';
+            accounts: [
+                {
+                    name: 'vault';
+                    isMut: true;
+                    isSigner: false;
+                },
+                {
+                    name: 'manager';
+                    isMut: false;
+                    isSigner: true;
+                }
+            ];
+            args: [
+                {
+                    name: 'fuelDistributionMode';
+                    type: 'u8';
+                }
+            ];
+        },
         {
             name: 'applyProfitShare';
             accounts: [
@@ -1722,13 +1821,23 @@ export type DriftVaults = {
                         type: 'u32';
                     },
                     {
-                        name: 'padding1';
+                        name: 'lastFuelUpdateTs';
                         type: 'u32';
                     },
+                    {
+                        name: 'cumulativeFuelPerShareAmount';
+                        docs: ['precision: FUEL_SHARE_PRECISION'];
+                        type: 'u128';
+                    },
+                    {
+                        name: 'fuelAmount';
+                        docs: ['precision: none'];
+                        type: 'u128';
+                    },
                     {
                         name: 'padding';
                         type: {
-                            array: ['u64', 8];
+                            array: ['u64', 4];
                         };
                     }
                 ];
@@ -2020,16 +2129,40 @@ export type DriftVaults = {
                         docs: ['The optional [`VaultProtocol`] account.'];
                         type: 'bool';
                     },
+                    {
+                        name: 'fuelDistributionMode';
+                        docs: [
+                            'How fuel distribution should be treated [`FuelDistributionMode`]. Default is `UsersOnly`'
+                        ];
+                        type: 'u8';
+                    },
                     {
                         name: 'padding1';
                         type: {
-                            array: ['u8', 7];
+                            array: ['u8', 2];
                         };
                     },
+                    {
+                        name: 'lastCumulativeFuelPerShareTs';
+                        docs: ['The timestamp cumulative_fuel_per_share was last updated'];
+                        type: 'u32';
+                    },
+                    {
+                        name: 'cumulativeFuelPerShare';
+                        docs: [
+                            'The cumulative fuel per share (scaled up by 1e6 to avoid losing precision)'
+                        ];
+                        type: 'u128';
+                    },
+                    {
+                        name: 'cumulativeFuel';
+                        docs: ['The total fuel accumulated'];
+                        type: 'u128';
+                    },
                     {
                         name: 'padding';
                         type: {
-                            array: ['u64', 7];
+                            array: ['u64', 3];
                         };
                     }
                 ];
@@ -2303,6 +2436,20 @@ export type DriftVaults = {
                 ];
             };
         },
+        {
+            name: 'FuelDistributionMode';
+            type: {
+                kind: 'enum';
+                variants: [
+                    {
+                        name: 'UsersOnly';
+                    },
+                    {
+                        name: 'UsersAndManager';
+                    }
+                ];
+            };
+        },
         {
             name: 'WithdrawUnit';
             type: {
@@ -2595,6 +2742,56 @@ export type DriftVaults = {
                     index: false;
                 }
             ];
+        },
+        {
+            name: 'FuelSeasonRecord';
+            fields: [
+                {
+                    name: 'ts';
+                    type: 'i64';
+                    index: false;
+                },
+                {
+                    name: 'authority';
+                    type: 'publicKey';
+                    index: false;
+                },
+                {
+                    name: 'fuelInsurance';
+                    type: 'u128';
+                    index: false;
+                },
+                {
+                    name: 'fuelDeposits';
+                    type: 'u128';
+                    index: false;
+                },
+                {
+                    name: 'fuelBorrows';
+                    type: 'u128';
+                    index: false;
+                },
+                {
+                    name: 'fuelPositions';
+                    type: 'u128';
+                    index: false;
+                },
+                {
+                    name: 'fuelTaker';
+                    type: 'u128';
+                    index: false;
+                },
+                {
+                    name: 'fuelMaker';
+                    type: 'u128';
+                    index: false;
+                },
+                {
+                    name: 'fuelTotal';
+                    type: 'u128';
+                    index: false;
+                }
+            ];
         }
     ];
     errors: [
@@ -2717,6 +2914,11 @@ export type DriftVaults = {
             code: 6023;
             name: 'InvalidTokenization';
             msg: 'InvalidTokenization';
+        },
+        {
+            code: 6024;
+            name: 'InvalidFuelDistributionMode';
+            msg: 'InvalidFuelDistributionMode';
         }
     ];
 };

package/lib/types/drift_vaults.js

@@ -2,7 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.IDL = void 0;
 exports.IDL = {
-    version: '0.2.0',
+    version: '0.4.0',
     name: 'drift_vaults',
     instructions: [
         {
@@ -279,6 +279,32 @@ exports.IDL = {
                 },
             ],
         },
+        {
+            name: 'updateCumulativeFuelAmount',
+            accounts: [
+                {
+                    name: 'vault',
+                    isMut: true,
+                    isSigner: false,
+                },
+                {
+                    name: 'vaultDepositor',
+                    isMut: true,
+                    isSigner: false,
+                },
+                {
+                    name: 'signer',
+                    isMut: false,
+                    isSigner: true,
+                },
+                {
+                    name: 'driftUserStats',
+                    isMut: true,
+                    isSigner: false,
+                },
+            ],
+            args: [],
+        },
         {
             name: 'initializeVaultDepositor',
             accounts: [
@@ -748,6 +774,58 @@ exports.IDL = {
             ],
             args: [],
         },
+        {
+            name: 'resetFuelSeason',
+            accounts: [
+                {
+                    name: 'vault',
+                    isMut: true,
+                    isSigner: false,
+                },
+                {
+                    name: 'vaultDepositor',
+                    isMut: true,
+                    isSigner: false,
+                },
+                {
+                    name: 'admin',
+                    isMut: false,
+                    isSigner: true,
+                },
+                {
+                    name: 'driftUserStats',
+                    isMut: true,
+                    isSigner: false,
+                },
+                {
+                    name: 'driftState',
+                    isMut: false,
+                    isSigner: false,
+                },
+            ],
+            args: [],
+        },
+        {
+            name: 'resetVaultFuelSeason',
+            accounts: [
+                {
+                    name: 'vault',
+                    isMut: true,
+                    isSigner: false,
+                },
+                {
+                    name: 'admin',
+                    isMut: false,
+                    isSigner: true,
+                },
+                {
+                    name: 'driftState',
+                    isMut: false,
+                    isSigner: false,
+                },
+            ],
+            args: [],
+        },
         {
             name: 'managerDeposit',
             accounts: [
@@ -933,6 +1011,27 @@ exports.IDL = {
             ],
             args: [],
         },
+        {
+            name: 'managerUpdateFuelDistributionMode',
+            accounts: [
+                {
+                    name: 'vault',
+                    isMut: true,
+                    isSigner: false,
+                },
+                {
+                    name: 'manager',
+                    isMut: false,
+                    isSigner: true,
+                },
+            ],
+            args: [
+                {
+                    name: 'fuelDistributionMode',
+                    type: 'u8',
+                },
+            ],
+        },
         {
             name: 'applyProfitShare',
             accounts: [
@@ -1725,13 +1824,23 @@ exports.IDL = {
                         type: 'u32',
                     },
                     {
-                        name: 'padding1',
+                        name: 'lastFuelUpdateTs',
                         type: 'u32',
                     },
+                    {
+                        name: 'cumulativeFuelPerShareAmount',
+                        docs: ['precision: FUEL_SHARE_PRECISION'],
+                        type: 'u128',
+                    },
+                    {
+                        name: 'fuelAmount',
+                        docs: ['precision: none'],
+                        type: 'u128',
+                    },
                     {
                         name: 'padding',
                         type: {
-                            array: ['u64', 8],
+                            array: ['u64', 4],
                         },
                     },
                 ],
@@ -2023,16 +2132,40 @@ exports.IDL = {
                         docs: ['The optional [`VaultProtocol`] account.'],
                         type: 'bool',
                     },
+                    {
+                        name: 'fuelDistributionMode',
+                        docs: [
+                            'How fuel distribution should be treated [`FuelDistributionMode`]. Default is `UsersOnly`',
+                        ],
+                        type: 'u8',
+                    },
                     {
                         name: 'padding1',
                         type: {
-                            array: ['u8', 7],
+                            array: ['u8', 2],
                         },
                     },
+                    {
+                        name: 'lastCumulativeFuelPerShareTs',
+                        docs: ['The timestamp cumulative_fuel_per_share was last updated'],
+                        type: 'u32',
+                    },
+                    {
+                        name: 'cumulativeFuelPerShare',
+                        docs: [
+                            'The cumulative fuel per share (scaled up by 1e6 to avoid losing precision)',
+                        ],
+                        type: 'u128',
+                    },
+                    {
+                        name: 'cumulativeFuel',
+                        docs: ['The total fuel accumulated'],
+                        type: 'u128',
+                    },
                     {
                         name: 'padding',
                         type: {
-                            array: ['u64', 7],
+                            array: ['u64', 3],
                         },
                     },
                 ],
@@ -2306,6 +2439,20 @@ exports.IDL = {
                 ],
             },
         },
+        {
+            name: 'FuelDistributionMode',
+            type: {
+                kind: 'enum',
+                variants: [
+                    {
+                        name: 'UsersOnly',
+                    },
+                    {
+                        name: 'UsersAndManager',
+                    },
+                ],
+            },
+        },
         {
             name: 'WithdrawUnit',
             type: {
@@ -2599,6 +2746,56 @@ exports.IDL = {
                 },
             ],
         },
+        {
+            name: 'FuelSeasonRecord',
+            fields: [
+                {
+                    name: 'ts',
+                    type: 'i64',
+                    index: false,
+                },
+                {
+                    name: 'authority',
+                    type: 'publicKey',
+                    index: false,
+                },
+                {
+                    name: 'fuelInsurance',
+                    type: 'u128',
+                    index: false,
+                },
+                {
+                    name: 'fuelDeposits',
+                    type: 'u128',
+                    index: false,
+                },
+                {
+                    name: 'fuelBorrows',
+                    type: 'u128',
+                    index: false,
+                },
+                {
+                    name: 'fuelPositions',
+                    type: 'u128',
+                    index: false,
+                },
+                {
+                    name: 'fuelTaker',
+                    type: 'u128',
+                    index: false,
+                },
+                {
+                    name: 'fuelMaker',
+                    type: 'u128',
+                    index: false,
+                },
+                {
+                    name: 'fuelTotal',
+                    type: 'u128',
+                    index: false,
+                },
+            ],
+        },
     ],
     errors: [
         {
@@ -2721,5 +2918,10 @@ exports.IDL = {
             name: 'InvalidTokenization',
             msg: 'InvalidTokenization',
         },
+        {
+            code: 6024,
+            name: 'InvalidFuelDistributionMode',
+            msg: 'InvalidFuelDistributionMode',
+        },
     ],
 };