Merge pull request #241 from Olamidepy/feat/issue-174-auction-protocols

feat: implement auction (English/Dutch) computation tools (#174)

Author: adams813

src/index.ts

@@ -28,6 +28,7 @@ import { sorobanMath } from './tools/soroban_math.js';
 import { decodeLedgerEntryTool, decodeLedgerEntrySchema } from './tools/decode_ledger_entry.js';
 import { computeVestingSchedule } from './tools/compute_vesting_schedule.js';
 import { deployContract } from './tools/deploy_contract.js';
+import { calculateDutchAuctionPrice, calculateEnglishAuctionState } from './tools/auction_compute.js';
 import { manageDaoTreasury } from './tools/manage_dao_treasury.js';
 import { computeInterestRates, calculateBorrowingCapacity } from './tools/lending_compute.js';
 import { trackLedgerConsensusTime } from './tools/track_ledger_consensus_time.js';
@@ -62,6 +63,9 @@ import {
   SorobanMathInputSchema,
   ComputeVestingScheduleInputSchema,
   DeployContractInputSchema,
+  CalculateDutchAuctionPriceInputSchema,
+  CalculateEnglishAuctionStateInputSchema,
+} from './schemas/tools.js';
   ManageDaoTreasuryInputSchema,
   ComputeInterestRatesInputSchema,
   CalculateBorrowingCapacityInputSchema,
@@ -706,6 +710,37 @@ class PulsarServer {
     },
   },
   {
+    name: 'calculate_dutch_auction_price',
+    description: 'Calculate the current price of an asset in a Dutch auction (linear price decay). Useful for NFT drops or fair price discovery.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        start_price: { type: 'number', description: 'Initial auction price.' },
+        reserve_price: { type: 'number', description: 'Minimum/floor price.' },
+        start_timestamp: { type: 'number', description: 'Unix timestamp when decay begins.' },
+        end_timestamp: { type: 'number', description: 'Unix timestamp when price reaches reserve.' },
+        current_timestamp: { type: 'number', description: 'Optional override for current time.' },
+      },
+      required: ['start_price', 'reserve_price', 'start_timestamp', 'end_timestamp'],
+    },
+  },
+  {
+    name: 'calculate_english_auction_state',
+    description: 'Calculate the next bid requirements and state for an English auction.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        current_highest_bid: { type: 'number', description: 'Current top bid (0 if no bids).' },
+        reserve_price: { type: 'number', description: 'Minimum bid to win/start.' },
+        bid_increment: { type: 'number', description: 'Required increase over the current bid.' },
+        bid_increment_type: { type: 'string', enum: ['absolute', 'percentage'], default: 'absolute' },
+        end_timestamp: { type: 'number', description: 'Unix timestamp when auction ends.' },
+        current_timestamp: { type: 'number', description: 'Optional override for current time.' },
+      },
+      required: ['current_highest_bid', 'reserve_price', 'bid_increment', 'end_timestamp'],
+    },
+  },
+],
     name: 'compute_interest_rates',
     description: 'Calculate borrow and supply interest rates using a Jump Rate Model (standard for protocols like Aave). Useful for simulating lending pool dynamics.',
     inputSchema: {
@@ -1496,6 +1531,9 @@ class PulsarServer {
           case 'get_account_balance': {
             const parsed = GetAccountBalanceInputSchema.safeParse(args);
             if (!parsed.success) {
+              throw new PulsarValidationError(`Invalid input for get_account_balance`, parsed.error.format());
+            }
+            const result = await getAccountBalance(parsed.data);
               throw new PulsarValidationError(
                 `Invalid input for get_account_balance`,
                 parsed.error.format()
@@ -2053,6 +2091,21 @@ class PulsarServer {
             };
           }
 
+          case 'calculate_dutch_auction_price': {
+            const parsed = CalculateDutchAuctionPriceInputSchema.safeParse(args);
+            if (!parsed.success) {
+              throw new PulsarValidationError(`Invalid input for calculate_dutch_auction_price`, parsed.error.format());
+            }
+            const result = await calculateDutchAuctionPrice(parsed.data);
+            return { content: [{ type: 'text', text: JSON.stringify(result) }] };
+          }
+
+          case 'calculate_english_auction_state': {
+            const parsed = CalculateEnglishAuctionStateInputSchema.safeParse(args);
+            if (!parsed.success) {
+              throw new PulsarValidationError(`Invalid input for calculate_english_auction_state`, parsed.error.format());
+            }
+            const result = await calculateEnglishAuctionState(parsed.data);
           case 'compute_interest_rates': {
             const parsed = ComputeInterestRatesInputSchema.safeParse(args);
             if (!parsed.success) {

src/schemas/tools.ts

@@ -221,6 +221,52 @@ export const EmergencyPauseInputSchema = z.object({
 
 export type EmergencyPauseInput = z.infer<typeof EmergencyPauseInputSchema>;
 
+/**
+ * Schema for calculate_dutch_auction_price tool
+ *
+ * Inputs:
+ * - start_price: Initial price of the asset
+ * - reserve_price: Minimum price (bottom of the curve)
+ * - start_timestamp: Unix timestamp when price begins to decay
+ * - end_timestamp: Unix timestamp when price reaches reserve
+ * - current_timestamp: Optional override for current time
+ */
+export const CalculateDutchAuctionPriceInputSchema = z.object({
+  start_price: z.number().positive(),
+  reserve_price: z.number().positive(),
+  start_timestamp: z.number().int().positive(),
+  end_timestamp: z.number().int().positive(),
+  current_timestamp: z.number().int().positive().optional(),
+});
+
+export type CalculateDutchAuctionPriceInput = z.infer<
+  typeof CalculateDutchAuctionPriceInputSchema
+>;
+
+/**
+ * Schema for calculate_english_auction_state tool
+ *
+ * Inputs:
+ * - current_highest_bid: The current bid to beat (0 if none)
+ * - reserve_price: Minimum bid required to start or win
+ * - bid_increment: Minimum amount or percentage to add to the highest bid
+ * - bid_increment_type: 'absolute' | 'percentage'
+ * - end_timestamp: Unix timestamp when the auction ends
+ * - current_timestamp: Optional override for current time
+ */
+export const CalculateEnglishAuctionStateInputSchema = z.object({
+  current_highest_bid: z.number().nonnegative(),
+  reserve_price: z.number().positive(),
+  bid_increment: z.number().positive(),
+  bid_increment_type: z.enum(["absolute", "percentage"]).default("absolute"),
+  end_timestamp: z.number().int().positive(),
+  current_timestamp: z.number().int().positive().optional(),
+});
+
+export type CalculateEnglishAuctionStateInput = z.infer<
+  typeof CalculateEnglishAuctionStateInputSchema
+>;
+
 /**
  * Schema for generate_contract_docs tool
  *

src/tools/auction_compute.ts

@@ -0,0 +1,90 @@
+import { 
+  CalculateDutchAuctionPriceInput, 
+  CalculateEnglishAuctionStateInput 
+} from "../schemas/tools.js";
+
+/**
+ * Calculates the current price of an asset in a Dutch auction with linear decay.
+ */
+export async function calculateDutchAuctionPrice(input: CalculateDutchAuctionPriceInput) {
+  const { 
+    start_price, 
+    reserve_price, 
+    start_timestamp, 
+    end_timestamp, 
+    current_timestamp = Math.floor(Date.now() / 1000) 
+  } = input;
+
+  if (current_timestamp <= start_timestamp) {
+    return {
+      status: "UPCOMING",
+      current_price: start_price.toFixed(7),
+      time_until_start: start_timestamp - current_timestamp,
+    };
+  }
+
+  if (current_timestamp >= end_timestamp) {
+    return {
+      status: "ENDED",
+      current_price: reserve_price.toFixed(7),
+      time_since_end: current_timestamp - end_timestamp,
+    };
+  }
+
+  // Linear decay: Price = Start - (Elapsed / TotalDuration) * (Start - Reserve)
+  const elapsed = current_timestamp - start_timestamp;
+  const total_duration = end_timestamp - start_timestamp;
+  const price_drop = (elapsed / total_duration) * (start_price - reserve_price);
+  const current_price = start_price - price_drop;
+
+  return {
+    status: "ACTIVE",
+    current_price: current_price.toFixed(7),
+    elapsed_seconds: elapsed,
+    remaining_seconds: end_timestamp - current_timestamp,
+    progress_percentage: ((elapsed / total_duration) * 100).toFixed(2),
+  };
+}
+
+/**
+ * Calculates the next bid requirements for an English auction.
+ */
+export async function calculateEnglishAuctionState(input: CalculateEnglishAuctionStateInput) {
+  const { 
+    current_highest_bid, 
+    reserve_price, 
+    bid_increment, 
+    bid_increment_type, 
+    end_timestamp, 
+    current_timestamp = Math.floor(Date.now() / 1000) 
+  } = input;
+
+  const is_ended = current_timestamp >= end_timestamp;
+  
+  let min_next_bid: number;
+  
+  if (current_highest_bid === 0) {
+    // No bids yet, next bid must be at least reserve price
+    min_next_bid = reserve_price;
+  } else {
+    // Calculate increment
+    const increment = bid_increment_type === 'percentage' 
+      ? current_highest_bid * (bid_increment / 100) 
+      : bid_increment;
+    
+    min_next_bid = current_highest_bid + increment;
+  }
+
+  return {
+    status: is_ended ? "ENDED" : "ACTIVE",
+    current_highest_bid: current_highest_bid.toFixed(7),
+    min_next_bid: min_next_bid.toFixed(7),
+    reserve_price: reserve_price.toFixed(7),
+    is_reserve_met: current_highest_bid >= reserve_price,
+    time_remaining: Math.max(0, end_timestamp - current_timestamp),
+    bid_increment_details: {
+      type: bid_increment_type,
+      value: bid_increment,
+    }
+  };
+}

tests/unit/auction_compute.test.ts

@@ -0,0 +1,113 @@
+import { describe, it, expect } from 'vitest';
+import { calculateDutchAuctionPrice, calculateEnglishAuctionState } from '../../src/tools/auction_compute.js';
+
+describe('Auction Computations', () => {
+  describe('calculateDutchAuctionPrice', () => {
+    const start_timestamp = 1700000000;
+    const end_timestamp = 1700010000; // 10000s duration
+    const start_price = 1000;
+    const reserve_price = 500;
+
+    it('returns start price before auction starts', async () => {
+      const result = await calculateDutchAuctionPrice({
+        start_price,
+        reserve_price,
+        start_timestamp,
+        end_timestamp,
+        current_timestamp: start_timestamp - 100,
+      });
+
+      expect(result.status).toBe('UPCOMING');
+      expect(result.current_price).toBe('1000.0000000');
+    });
+
+    it('calculates price halfway through the auction', async () => {
+      const result = await calculateDutchAuctionPrice({
+        start_price,
+        reserve_price,
+        start_timestamp,
+        end_timestamp,
+        current_timestamp: start_timestamp + 5000,
+      });
+
+      // 50% through: 1000 - 0.5 * (1000 - 500) = 1000 - 250 = 750
+      expect(result.status).toBe('ACTIVE');
+      expect(result.current_price).toBe('750.0000000');
+      expect(result.progress_percentage).toBe('50.00');
+    });
+
+    it('returns reserve price after auction ends', async () => {
+      const result = await calculateDutchAuctionPrice({
+        start_price,
+        reserve_price,
+        start_timestamp,
+        end_timestamp,
+        current_timestamp: end_timestamp + 100,
+      });
+
+      expect(result.status).toBe('ENDED');
+      expect(result.current_price).toBe('500.0000000');
+    });
+  });
+
+  describe('calculateEnglishAuctionState', () => {
+    const end_timestamp = 1700000000;
+    const reserve_price = 100;
+
+    it('calculates min bid when no bids exist', async () => {
+      const result = await calculateEnglishAuctionState({
+        current_highest_bid: 0,
+        reserve_price,
+        bid_increment: 10,
+        bid_increment_type: 'absolute',
+        end_timestamp,
+        current_timestamp: end_timestamp - 100,
+      });
+
+      expect(result.status).toBe('ACTIVE');
+      expect(result.min_next_bid).toBe('100.0000000'); // Must beat reserve
+      expect(result.is_reserve_met).toBe(false);
+    });
+
+    it('calculates absolute bid increment', async () => {
+      const result = await calculateEnglishAuctionState({
+        current_highest_bid: 150,
+        reserve_price,
+        bid_increment: 10,
+        bid_increment_type: 'absolute',
+        end_timestamp,
+        current_timestamp: end_timestamp - 100,
+      });
+
+      expect(result.min_next_bid).toBe('160.0000000');
+      expect(result.is_reserve_met).toBe(true);
+    });
+
+    it('calculates percentage bid increment', async () => {
+      const result = await calculateEnglishAuctionState({
+        current_highest_bid: 200,
+        reserve_price,
+        bid_increment: 5, // 5%
+        bid_increment_type: 'percentage',
+        end_timestamp,
+        current_timestamp: end_timestamp - 100,
+      });
+
+      // 200 + 5% = 200 + 10 = 210
+      expect(result.min_next_bid).toBe('210.0000000');
+    });
+
+    it('handles ended auction state', async () => {
+      const result = await calculateEnglishAuctionState({
+        current_highest_bid: 250,
+        reserve_price,
+        bid_increment: 10,
+        end_timestamp,
+        current_timestamp: end_timestamp + 100,
+      });
+
+      expect(result.status).toBe('ENDED');
+      expect(result.time_remaining).toBe(0);
+    });
+  });
+});