pyre-world-kit 1.0.8 → 1.0.10

package/dist/actions.d.ts

@@ -6,7 +6,13 @@
  */
 import { Connection, PublicKey } from '@solana/web3.js';
 import type { BuyQuoteResult, SellQuoteResult, TransactionResult, SaidVerification, ConfirmResult } from 'torchsdk';
-import type { FactionListParams, FactionListResult, FactionDetail, MembersResult, CommsResult, Stronghold, AgentLink, WarChest, WarLoan, AllWarLoansResult, LaunchFactionParams, JoinFactionParams, DirectJoinFactionParams, DefectParams, RallyParams, RequestWarLoanParams, RepayWarLoanParams, SiegeParams, TradeOnDexParams, ClaimSpoilsParams, CreateStrongholdParams, FundStrongholdParams, WithdrawFromStrongholdParams, RecruitAgentParams, ExileAgentParams, CoupParams, WithdrawAssetsParams, AscendParams, RazeParams, TitheParams, ConvertTitheParams, JoinFactionResult, LaunchFactionResult } from './types';
+import type { FactionListParams, FactionListResult, FactionDetail, MembersResult, CommsResult, Stronghold, AgentLink, WarChest, WarLoan, WarLoanQuote, AllWarLoansResult, LaunchFactionParams, JoinFactionParams, DirectJoinFactionParams, DefectParams, RallyParams, RequestWarLoanParams, RepayWarLoanParams, SiegeParams, TradeOnDexParams, ClaimSpoilsParams, CreateStrongholdParams, FundStrongholdParams, WithdrawFromStrongholdParams, RecruitAgentParams, ExileAgentParams, CoupParams, WithdrawAssetsParams, AscendParams, RazeParams, TitheParams, ConvertTitheParams, JoinFactionResult, LaunchFactionResult } from './types';
+/** Add mints to the blacklist (call at startup with old mints) */
+export declare function blacklistMints(mints: string[]): void;
+/** Check if a mint is blacklisted */
+export declare function isBlacklistedMint(mint: string): boolean;
+/** Get all blacklisted mints */
+export declare function getBlacklistedMints(): string[];
 /** List all factions with optional filtering and sorting */
 export declare function getFactions(connection: Connection, params?: FactionListParams): Promise<FactionListResult>;
 /** Get detailed info for a single faction */
@@ -31,6 +37,18 @@ export declare function getWarChest(connection: Connection, mint: string): Promi
 export declare function getWarLoan(connection: Connection, mint: string, wallet: string): Promise<WarLoan>;
 /** Get all war loans for a faction */
 export declare function getAllWarLoans(connection: Connection, mint: string): Promise<AllWarLoansResult>;
+/**
+ * Compute max borrowable SOL for a given collateral amount.
+ *
+ * Mirrors the burnfun LendingDashboard logic — effective max borrow is the
+ * minimum of three caps:
+ *   1. LTV limit: collateral_value_sol * (max_ltv_bps / 10000)
+ *   2. Pool available: treasury_sol * utilization_cap - total_lent
+ *   3. Per-user cap: (collateral / total_supply) * borrow_share_multiplier * max_lendable
+ *
+ * All values in lamports. Accounts for Token-2022 transfer fee (4 bps).
+ */
+export declare function getMaxWarLoan(connection: Connection, mint: string, collateralAmount: number): Promise<WarLoanQuote>;
 /** Launch a new faction (create token) */
 export declare function launchFaction(connection: Connection, params: LaunchFactionParams): Promise<LaunchFactionResult>;
 /** Join a faction via stronghold (vault-funded buy) */

package/dist/actions.js

@@ -10,6 +10,9 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createEphemeralAgent = void 0;
+exports.blacklistMints = blacklistMints;
+exports.isBlacklistedMint = isBlacklistedMint;
+exports.getBlacklistedMints = getBlacklistedMints;
 exports.getFactions = getFactions;
 exports.getFaction = getFaction;
 exports.getMembers = getMembers;
@@ -22,6 +25,7 @@ exports.getAgentLink = getAgentLink;
 exports.getWarChest = getWarChest;
 exports.getWarLoan = getWarLoan;
 exports.getAllWarLoans = getAllWarLoans;
+exports.getMaxWarLoan = getMaxWarLoan;
 exports.launchFaction = launchFaction;
 exports.joinFaction = joinFaction;
 exports.directJoinFaction = directJoinFaction;
@@ -52,6 +56,23 @@ const bs58_1 = __importDefault(require("bs58"));
 const torchsdk_1 = require("torchsdk");
 const mappers_1 = require("./mappers");
 const vanity_1 = require("./vanity");
+// ─── Blacklist ──────────────────────────────────────────────────────
+// Mints from previous swarm runs. Agents should skip these and only
+// interact with freshly launched factions.
+const BLACKLISTED_MINTS = new Set();
+/** Add mints to the blacklist (call at startup with old mints) */
+function blacklistMints(mints) {
+    for (const m of mints)
+        BLACKLISTED_MINTS.add(m);
+}
+/** Check if a mint is blacklisted */
+function isBlacklistedMint(mint) {
+    return BLACKLISTED_MINTS.has(mint);
+}
+/** Get all blacklisted mints */
+function getBlacklistedMints() {
+    return Array.from(BLACKLISTED_MINTS);
+}
 // ─── Read Operations ───────────────────────────────────────────────
 /** List all factions with optional filtering and sorting */
 async function getFactions(connection, params) {
@@ -62,38 +83,7 @@ async function getFactions(connection, params) {
         sort: params.sort,
     } : undefined;
     const result = await (0, torchsdk_1.getTokens)(connection, sdkParams);
-    const listResult = (0, mappers_1.mapTokenListResult)(result);
-    // Enrich ascended factions with live pool price (list endpoint only has stale bonding curve mcap)
-    // Use Promise.allSettled so a single failure doesn't block/break the list
-    const ascended = listResult.factions.filter(f => f.status === 'ascended');
-    if (ascended.length > 0) {
-        const enrichPromise = Promise.allSettled(ascended.map(async (faction) => {
-            const mint = new web3_js_1.PublicKey(faction.mint);
-            const raydium = (0, torchsdk_1.getRaydiumMigrationAccounts)(mint);
-            const [vault0Info, vault1Info] = await Promise.all([
-                connection.getTokenAccountBalance(raydium.token0Vault),
-                connection.getTokenAccountBalance(raydium.token1Vault),
-            ]);
-            const vault0 = Number(vault0Info.value.amount);
-            const vault1 = Number(vault1Info.value.amount);
-            const solReserves = raydium.isWsolToken0 ? vault0 : vault1;
-            const tokenReserves = raydium.isWsolToken0 ? vault1 : vault0;
-            if (tokenReserves > 0) {
-                const LAMPORTS = 1_000_000_000;
-                const TOKEN_MUL = 1_000_000;
-                const priceInSol = (solReserves * TOKEN_MUL) / (tokenReserves * LAMPORTS);
-                const TOTAL_SUPPLY = 1_000_000_000 * TOKEN_MUL;
-                faction.price_sol = priceInSol;
-                faction.market_cap_sol = (priceInSol * TOTAL_SUPPLY) / TOKEN_MUL;
-            }
-        }));
-        // Race enrichment against a 3s timeout so the list always loads
-        await Promise.race([
-            enrichPromise,
-            new Promise(resolve => setTimeout(resolve, 3000)),
-        ]);
-    }
-    return listResult;
+    return (0, mappers_1.mapTokenListResult)(result);
 }
 /** Get detailed info for a single faction */
 async function getFaction(connection, mint) {
@@ -222,6 +212,53 @@ async function getAllWarLoans(connection, mint) {
     const result = await (0, torchsdk_1.getAllLoanPositions)(connection, mint);
     return (0, mappers_1.mapAllLoansResult)(result);
 }
+/**
+ * Compute max borrowable SOL for a given collateral amount.
+ *
+ * Mirrors the burnfun LendingDashboard logic — effective max borrow is the
+ * minimum of three caps:
+ *   1. LTV limit: collateral_value_sol * (max_ltv_bps / 10000)
+ *   2. Pool available: treasury_sol * utilization_cap - total_lent
+ *   3. Per-user cap: (collateral / total_supply) * borrow_share_multiplier * max_lendable
+ *
+ * All values in lamports. Accounts for Token-2022 transfer fee (4 bps).
+ */
+async function getMaxWarLoan(connection, mint, collateralAmount) {
+    const TOTAL_SUPPLY = 1_000_000_000_000_000; // 1B tokens * 1e6 multiplier (base units)
+    const TRANSFER_FEE_BPS = 4;
+    const LAMPORTS_PER_SOL = 1_000_000_000;
+    const [lending, detail] = await Promise.all([
+        (0, torchsdk_1.getLendingInfo)(connection, mint),
+        (0, torchsdk_1.getToken)(connection, mint),
+    ]);
+    // Price per base-unit token in SOL (lamports)
+    const pricePerToken = detail.price_sol; // SOL per display token
+    const TOKEN_MULTIPLIER = 1_000_000;
+    // Collateral value in SOL (lamports)
+    const collateralDisplayTokens = collateralAmount / TOKEN_MULTIPLIER;
+    const collateralValueSol = collateralDisplayTokens * pricePerToken * LAMPORTS_PER_SOL;
+    // 1. LTV cap
+    const ltvMaxSol = collateralValueSol * (lending.max_ltv_bps / 10000);
+    // 2. Pool available
+    const treasurySol = detail.treasury_sol_balance * LAMPORTS_PER_SOL;
+    const maxLendableSol = treasurySol * lending.utilization_cap_bps / 10000;
+    const totalLent = (lending.total_sol_lent ?? 0);
+    const poolAvailableSol = Math.max(0, maxLendableSol - totalLent);
+    // 3. Per-user cap (accounts for transfer fee reducing net collateral)
+    const netCollateral = collateralAmount * (1 - TRANSFER_FEE_BPS / 10000);
+    const borrowMultiplier = lending.borrow_share_multiplier || 3;
+    const perUserCapSol = maxLendableSol * netCollateral * borrowMultiplier / TOTAL_SUPPLY;
+    const maxBorrowSol = Math.max(0, Math.min(ltvMaxSol, poolAvailableSol, perUserCapSol));
+    return {
+        max_borrow_sol: Math.floor(maxBorrowSol),
+        collateral_value_sol: Math.floor(collateralValueSol),
+        ltv_max_sol: Math.floor(ltvMaxSol),
+        pool_available_sol: Math.floor(poolAvailableSol),
+        per_user_cap_sol: Math.floor(perUserCapSol),
+        interest_rate_bps: lending.interest_rate_bps,
+        liquidation_threshold_bps: lending.liquidation_threshold_bps,
+    };
+}
 // ─── Faction Operations (controller) ───────────────────────────────
 /** Launch a new faction (create token) */
 async function launchFaction(connection, params) {

package/dist/index.d.ts

@@ -5,8 +5,8 @@
  * This kit translates protocol primitives into faction warfare language
  * so agents think in factions, not tokens.
  */
-export type { FactionStatus, FactionTier, Strategy, AgentHealth, FactionSummary, FactionDetail, Stronghold, AgentLink, Comms, WarChest, WarLoan, WarLoanWithAgent, Member, FactionListResult, MembersResult, CommsResult, AllWarLoansResult, LaunchFactionParams, JoinFactionParams, DirectJoinFactionParams, DefectParams, RallyParams, RequestWarLoanParams, RepayWarLoanParams, SiegeParams, TradeOnDexParams, ClaimSpoilsParams, CreateStrongholdParams, FundStrongholdParams, WithdrawFromStrongholdParams, RecruitAgentParams, ExileAgentParams, CoupParams, WithdrawAssetsParams, AscendParams, RazeParams, TitheParams, ConvertTitheParams, JoinFactionResult, LaunchFactionResult, TransactionResult, EphemeralAgent, SaidVerification, ConfirmResult, FactionSortOption, FactionStatusFilter, FactionListParams, FactionPower, AllianceCluster, RivalFaction, AgentProfile, AgentFactionPosition, WorldEventType, WorldEvent, WorldStats, } from './types';
-export { getFactions, getFaction, getMembers, getComms, getJoinQuote, getDefectQuote, getStronghold, getStrongholdForAgent, getAgentLink, getWarChest, getWarLoan, getAllWarLoans, launchFaction, joinFaction, directJoinFaction, defect, rally, requestWarLoan, repayWarLoan, tradeOnDex, claimSpoils, createStronghold, fundStronghold, withdrawFromStronghold, recruitAgent, exileAgent, coup, withdrawAssets, siege, ascend, raze, tithe, convertTithe, verifyAgent, confirmAction, createEphemeralAgent, getDexPool, getDexVaults, } from './actions';
+export type { FactionStatus, FactionTier, Strategy, AgentHealth, FactionSummary, FactionDetail, Stronghold, AgentLink, Comms, WarChest, WarLoan, WarLoanWithAgent, Member, FactionListResult, MembersResult, CommsResult, AllWarLoansResult, WarLoanQuote, LaunchFactionParams, JoinFactionParams, DirectJoinFactionParams, DefectParams, RallyParams, RequestWarLoanParams, RepayWarLoanParams, SiegeParams, TradeOnDexParams, ClaimSpoilsParams, CreateStrongholdParams, FundStrongholdParams, WithdrawFromStrongholdParams, RecruitAgentParams, ExileAgentParams, CoupParams, WithdrawAssetsParams, AscendParams, RazeParams, TitheParams, ConvertTitheParams, JoinFactionResult, LaunchFactionResult, TransactionResult, EphemeralAgent, SaidVerification, ConfirmResult, FactionSortOption, FactionStatusFilter, FactionListParams, FactionPower, AllianceCluster, RivalFaction, AgentProfile, AgentFactionPosition, WorldEventType, WorldEvent, WorldStats, } from './types';
+export { getFactions, getFaction, getMembers, getComms, getJoinQuote, getDefectQuote, getStronghold, getStrongholdForAgent, getAgentLink, getWarChest, getWarLoan, getAllWarLoans, getMaxWarLoan, blacklistMints, isBlacklistedMint, getBlacklistedMints, launchFaction, joinFaction, directJoinFaction, defect, rally, requestWarLoan, repayWarLoan, tradeOnDex, claimSpoils, createStronghold, fundStronghold, withdrawFromStronghold, recruitAgent, exileAgent, coup, withdrawAssets, siege, ascend, raze, tithe, convertTithe, verifyAgent, confirmAction, createEphemeralAgent, getDexPool, getDexVaults, } from './actions';
 export { getFactionPower, getFactionLeaderboard, detectAlliances, getFactionRivals, getAgentProfile, getAgentFactions, getWorldFeed, getWorldStats, } from './intel';
 export { isPyreMint, grindPyreMint } from './vanity';
 export { PROGRAM_ID, LAMPORTS_PER_SOL, TOKEN_MULTIPLIER, TOTAL_SUPPLY } from 'torchsdk';

package/dist/index.js

@@ -7,8 +7,8 @@
  * so agents think in factions, not tokens.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.LAMPORTS_PER_SOL = exports.PROGRAM_ID = exports.grindPyreMint = exports.isPyreMint = exports.getWorldStats = exports.getWorldFeed = exports.getAgentFactions = exports.getAgentProfile = exports.getFactionRivals = exports.detectAlliances = exports.getFactionLeaderboard = exports.getFactionPower = exports.getDexVaults = exports.getDexPool = exports.createEphemeralAgent = exports.confirmAction = exports.verifyAgent = exports.convertTithe = exports.tithe = exports.raze = exports.ascend = exports.siege = exports.withdrawAssets = exports.coup = exports.exileAgent = exports.recruitAgent = exports.withdrawFromStronghold = exports.fundStronghold = exports.createStronghold = exports.claimSpoils = exports.tradeOnDex = exports.repayWarLoan = exports.requestWarLoan = exports.rally = exports.defect = exports.directJoinFaction = exports.joinFaction = exports.launchFaction = exports.getAllWarLoans = exports.getWarLoan = exports.getWarChest = exports.getAgentLink = exports.getStrongholdForAgent = exports.getStronghold = exports.getDefectQuote = exports.getJoinQuote = exports.getComms = exports.getMembers = exports.getFaction = exports.getFactions = void 0;
-exports.TOTAL_SUPPLY = exports.TOKEN_MULTIPLIER = void 0;
+exports.getWorldStats = exports.getWorldFeed = exports.getAgentFactions = exports.getAgentProfile = exports.getFactionRivals = exports.detectAlliances = exports.getFactionLeaderboard = exports.getFactionPower = exports.getDexVaults = exports.getDexPool = exports.createEphemeralAgent = exports.confirmAction = exports.verifyAgent = exports.convertTithe = exports.tithe = exports.raze = exports.ascend = exports.siege = exports.withdrawAssets = exports.coup = exports.exileAgent = exports.recruitAgent = exports.withdrawFromStronghold = exports.fundStronghold = exports.createStronghold = exports.claimSpoils = exports.tradeOnDex = exports.repayWarLoan = exports.requestWarLoan = exports.rally = exports.defect = exports.directJoinFaction = exports.joinFaction = exports.launchFaction = exports.getBlacklistedMints = exports.isBlacklistedMint = exports.blacklistMints = exports.getMaxWarLoan = exports.getAllWarLoans = exports.getWarLoan = exports.getWarChest = exports.getAgentLink = exports.getStrongholdForAgent = exports.getStronghold = exports.getDefectQuote = exports.getJoinQuote = exports.getComms = exports.getMembers = exports.getFaction = exports.getFactions = void 0;
+exports.TOTAL_SUPPLY = exports.TOKEN_MULTIPLIER = exports.LAMPORTS_PER_SOL = exports.PROGRAM_ID = exports.grindPyreMint = exports.isPyreMint = void 0;
 // ─── Actions ───────────────────────────────────────────────────────
 var actions_1 = require("./actions");
 // Read operations
@@ -24,6 +24,11 @@ Object.defineProperty(exports, "getAgentLink", { enumerable: true, get: function
 Object.defineProperty(exports, "getWarChest", { enumerable: true, get: function () { return actions_1.getWarChest; } });
 Object.defineProperty(exports, "getWarLoan", { enumerable: true, get: function () { return actions_1.getWarLoan; } });
 Object.defineProperty(exports, "getAllWarLoans", { enumerable: true, get: function () { return actions_1.getAllWarLoans; } });
+Object.defineProperty(exports, "getMaxWarLoan", { enumerable: true, get: function () { return actions_1.getMaxWarLoan; } });
+// Blacklist
+Object.defineProperty(exports, "blacklistMints", { enumerable: true, get: function () { return actions_1.blacklistMints; } });
+Object.defineProperty(exports, "isBlacklistedMint", { enumerable: true, get: function () { return actions_1.isBlacklistedMint; } });
+Object.defineProperty(exports, "getBlacklistedMints", { enumerable: true, get: function () { return actions_1.getBlacklistedMints; } });
 // Faction operations
 Object.defineProperty(exports, "launchFaction", { enumerable: true, get: function () { return actions_1.launchFaction; } });
 Object.defineProperty(exports, "joinFaction", { enumerable: true, get: function () { return actions_1.joinFaction; } });

package/dist/types.d.ts

@@ -296,6 +296,23 @@ export interface FactionListParams {
     status?: FactionStatusFilter;
     sort?: FactionSortOption;
 }
+/** Result of computing max borrowable SOL for a given collateral amount */
+export interface WarLoanQuote {
+    /** Max SOL borrowable (lamports) — minimum of LTV cap, pool available, per-user cap */
+    max_borrow_sol: number;
+    /** Collateral value in SOL (lamports) */
+    collateral_value_sol: number;
+    /** LTV-limited max borrow (lamports) */
+    ltv_max_sol: number;
+    /** Pool available SOL (lamports) */
+    pool_available_sol: number;
+    /** Per-user cap SOL (lamports) — based on share of supply * borrow_share_multiplier */
+    per_user_cap_sol: number;
+    /** Current interest rate in bps per epoch */
+    interest_rate_bps: number;
+    /** Liquidation threshold in bps */
+    liquidation_threshold_bps: number;
+}
 export interface FactionPower {
     mint: string;
     name: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pyre-world-kit",
-  "version": "1.0.8",
+  "version": "1.0.10",
   "description": "Agent-first faction warfare kit — game-semantic wrapper over torchsdk",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/actions.ts

@@ -61,6 +61,7 @@ import type {
   AgentLink,
   WarChest,
   WarLoan,
+  WarLoanQuote,
   AllWarLoansResult,
   LaunchFactionParams,
   JoinFactionParams,
@@ -105,6 +106,27 @@ import {
 
 import { buildCreateFactionTransaction, isPyreMint } from './vanity';
 
+// ─── Blacklist ──────────────────────────────────────────────────────
+// Mints from previous swarm runs. Agents should skip these and only
+// interact with freshly launched factions.
+
+const BLACKLISTED_MINTS = new Set<string>();
+
+/** Add mints to the blacklist (call at startup with old mints) */
+export function blacklistMints(mints: string[]): void {
+  for (const m of mints) BLACKLISTED_MINTS.add(m);
+}
+
+/** Check if a mint is blacklisted */
+export function isBlacklistedMint(mint: string): boolean {
+  return BLACKLISTED_MINTS.has(mint);
+}
+
+/** Get all blacklisted mints */
+export function getBlacklistedMints(): string[] {
+  return Array.from(BLACKLISTED_MINTS);
+}
+
 // ─── Read Operations ───────────────────────────────────────────────
 
 /** List all factions with optional filtering and sorting */
@@ -119,41 +141,7 @@ export async function getFactions(
     sort: params.sort,
   } : undefined;
   const result = await getTokens(connection, sdkParams);
-  const listResult = mapTokenListResult(result);
-
-  // Enrich ascended factions with live pool price (list endpoint only has stale bonding curve mcap)
-  // Use Promise.allSettled so a single failure doesn't block/break the list
-  const ascended = listResult.factions.filter(f => f.status === 'ascended');
-  if (ascended.length > 0) {
-    const enrichPromise = Promise.allSettled(ascended.map(async (faction) => {
-      const mint = new PublicKey(faction.mint);
-      const raydium = getRaydiumMigrationAccounts(mint);
-      const [vault0Info, vault1Info] = await Promise.all([
-        connection.getTokenAccountBalance(raydium.token0Vault),
-        connection.getTokenAccountBalance(raydium.token1Vault),
-      ]);
-      const vault0 = Number(vault0Info.value.amount);
-      const vault1 = Number(vault1Info.value.amount);
-      const solReserves = raydium.isWsolToken0 ? vault0 : vault1;
-      const tokenReserves = raydium.isWsolToken0 ? vault1 : vault0;
-      if (tokenReserves > 0) {
-        const LAMPORTS = 1_000_000_000;
-        const TOKEN_MUL = 1_000_000;
-        const priceInSol = (solReserves * TOKEN_MUL) / (tokenReserves * LAMPORTS);
-        const TOTAL_SUPPLY = 1_000_000_000 * TOKEN_MUL;
-        faction.price_sol = priceInSol;
-        faction.market_cap_sol = (priceInSol * TOTAL_SUPPLY) / TOKEN_MUL;
-      }
-    }));
-
-    // Race enrichment against a 3s timeout so the list always loads
-    await Promise.race([
-      enrichPromise,
-      new Promise(resolve => setTimeout(resolve, 3000)),
-    ]);
-  }
-
-  return listResult;
+  return mapTokenListResult(result);
 }
 
 /** Get detailed info for a single faction */
@@ -352,6 +340,66 @@ export async function getAllWarLoans(
   return mapAllLoansResult(result);
 }
 
+/**
+ * Compute max borrowable SOL for a given collateral amount.
+ *
+ * Mirrors the burnfun LendingDashboard logic — effective max borrow is the
+ * minimum of three caps:
+ *   1. LTV limit: collateral_value_sol * (max_ltv_bps / 10000)
+ *   2. Pool available: treasury_sol * utilization_cap - total_lent
+ *   3. Per-user cap: (collateral / total_supply) * borrow_share_multiplier * max_lendable
+ *
+ * All values in lamports. Accounts for Token-2022 transfer fee (4 bps).
+ */
+export async function getMaxWarLoan(
+  connection: Connection,
+  mint: string,
+  collateralAmount: number,
+): Promise<WarLoanQuote> {
+  const TOTAL_SUPPLY = 1_000_000_000_000_000; // 1B tokens * 1e6 multiplier (base units)
+  const TRANSFER_FEE_BPS = 4;
+  const LAMPORTS_PER_SOL = 1_000_000_000;
+
+  const [lending, detail] = await Promise.all([
+    getLendingInfo(connection, mint),
+    getToken(connection, mint),
+  ]);
+
+  // Price per base-unit token in SOL (lamports)
+  const pricePerToken = detail.price_sol; // SOL per display token
+  const TOKEN_MULTIPLIER = 1_000_000;
+
+  // Collateral value in SOL (lamports)
+  const collateralDisplayTokens = collateralAmount / TOKEN_MULTIPLIER;
+  const collateralValueSol = collateralDisplayTokens * pricePerToken * LAMPORTS_PER_SOL;
+
+  // 1. LTV cap
+  const ltvMaxSol = collateralValueSol * (lending.max_ltv_bps / 10000);
+
+  // 2. Pool available
+  const treasurySol = detail.treasury_sol_balance * LAMPORTS_PER_SOL;
+  const maxLendableSol = treasurySol * lending.utilization_cap_bps / 10000;
+  const totalLent = (lending.total_sol_lent ?? 0);
+  const poolAvailableSol = Math.max(0, maxLendableSol - totalLent);
+
+  // 3. Per-user cap (accounts for transfer fee reducing net collateral)
+  const netCollateral = collateralAmount * (1 - TRANSFER_FEE_BPS / 10000);
+  const borrowMultiplier = lending.borrow_share_multiplier || 3;
+  const perUserCapSol = maxLendableSol * netCollateral * borrowMultiplier / TOTAL_SUPPLY;
+
+  const maxBorrowSol = Math.max(0, Math.min(ltvMaxSol, poolAvailableSol, perUserCapSol));
+
+  return {
+    max_borrow_sol: Math.floor(maxBorrowSol),
+    collateral_value_sol: Math.floor(collateralValueSol),
+    ltv_max_sol: Math.floor(ltvMaxSol),
+    pool_available_sol: Math.floor(poolAvailableSol),
+    per_user_cap_sol: Math.floor(perUserCapSol),
+    interest_rate_bps: lending.interest_rate_bps,
+    liquidation_threshold_bps: lending.liquidation_threshold_bps,
+  };
+}
+
 // ─── Faction Operations (controller) ───────────────────────────────
 
 /** Launch a new faction (create token) */

package/src/index.ts

@@ -29,6 +29,7 @@ export type {
   MembersResult,
   CommsResult,
   AllWarLoansResult,
+  WarLoanQuote,
   // Params
   LaunchFactionParams,
   JoinFactionParams,
@@ -89,6 +90,11 @@ export {
   getWarChest,
   getWarLoan,
   getAllWarLoans,
+  getMaxWarLoan,
+  // Blacklist
+  blacklistMints,
+  isBlacklistedMint,
+  getBlacklistedMints,
   // Faction operations
   launchFaction,
   joinFaction,

package/src/types.ts

@@ -360,6 +360,26 @@ export interface FactionListParams {
   sort?: FactionSortOption;
 }
 
+// ─── War Loan Quote ─────────────────────────────────────────────
+
+/** Result of computing max borrowable SOL for a given collateral amount */
+export interface WarLoanQuote {
+  /** Max SOL borrowable (lamports) — minimum of LTV cap, pool available, per-user cap */
+  max_borrow_sol: number;
+  /** Collateral value in SOL (lamports) */
+  collateral_value_sol: number;
+  /** LTV-limited max borrow (lamports) */
+  ltv_max_sol: number;
+  /** Pool available SOL (lamports) */
+  pool_available_sol: number;
+  /** Per-user cap SOL (lamports) — based on share of supply * borrow_share_multiplier */
+  per_user_cap_sol: number;
+  /** Current interest rate in bps per epoch */
+  interest_rate_bps: number;
+  /** Liquidation threshold in bps */
+  liquidation_threshold_bps: number;
+}
+
 // ─── Intel Types ───────────────────────────────────────────────────
 
 export interface FactionPower {