@terkoizmy/intent-sdk 1.0.0

package/dist/solver/monitoring/profit-tracker.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Profit Tracker — Phase H
+ *
+ * Tracks expected vs actual profit for solved intents and provides
+ * aggregate statistics for the LiquidityAgent operator.
+ *
+ * Used by: LiquidityAgent
+ */
+import type { PricingResult } from "../types/pricing";
+export interface ProfitRecord {
+    intentId: string;
+    pricing: PricingResult;
+    success?: boolean;
+    actualGasUsed?: string;
+    netProfit?: string;
+    timestamp: number;
+}
+export interface ProfitStats {
+    totalProfit: string;
+    totalGasCost: string;
+    successCount: number;
+    failCount: number;
+    avgProfit: string;
+    totalAttempts: number;
+}
+export declare class ProfitTracker {
+    private records;
+    /** Timestamp of the first ever recordAttempt call — used for ROI period */
+    private startedAt;
+    /**
+     * Record an intent that the agent is attempting to solve
+     */
+    recordAttempt(intentId: string, pricing: PricingResult): void;
+    /**
+     * Record the final result of an attempted intent
+     */
+    recordResult(intentId: string, success: boolean, gasUsed?: string): void;
+    /**
+     * Get aggregate statistics
+     */
+    getStats(periodMs?: number): ProfitStats;
+    /**
+     * Get annualized ROI percentage based on capital deployed
+     */
+    getROI(capitalDeployed: string): number;
+}
+//# sourceMappingURL=profit-tracker.d.ts.map

package/dist/solver/monitoring/profit-tracker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"profit-tracker.d.ts","sourceRoot":"","sources":["../../../src/solver/monitoring/profit-tracker.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAEtD,MAAM,WAAW,YAAY;IACzB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,aAAa,CAAC;IACvB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,WAAW;IACxB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,MAAM,CAAC;CACzB;AAED,qBAAa,aAAa;IACtB,OAAO,CAAC,OAAO,CAAwC;IACvD,2EAA2E;IAC3E,OAAO,CAAC,SAAS,CAAuB;IAExC;;OAEG;IACH,aAAa,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,aAAa,GAAG,IAAI;IAkB7D;;OAEG;IACH,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI;IAqBxE;;OAEG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,WAAW;IAmCxC;;OAEG;IACH,MAAM,CAAC,eAAe,EAAE,MAAM,GAAG,MAAM;CAuB1C"}

package/dist/solver/monitoring/profit-tracker.js

@@ -0,0 +1,112 @@
+/**
+ * Profit Tracker — Phase H
+ *
+ * Tracks expected vs actual profit for solved intents and provides
+ * aggregate statistics for the LiquidityAgent operator.
+ *
+ * Used by: LiquidityAgent
+ */
+export class ProfitTracker {
+    records = new Map();
+    /** Timestamp of the first ever recordAttempt call — used for ROI period */
+    startedAt = null;
+    /**
+     * Record an intent that the agent is attempting to solve
+     */
+    recordAttempt(intentId, pricing) {
+        // Guard: warn if this intent is already tracked but not yet resolved
+        const existing = this.records.get(intentId);
+        if (existing && existing.success === undefined) {
+            console.warn(`[ProfitTracker] Overwriting in-flight record for intent: ${intentId}`);
+        }
+        if (this.startedAt === null) {
+            this.startedAt = Date.now();
+        }
+        this.records.set(intentId, {
+            intentId,
+            pricing,
+            timestamp: Date.now(),
+        });
+    }
+    /**
+     * Record the final result of an attempted intent
+     */
+    recordResult(intentId, success, gasUsed) {
+        const record = this.records.get(intentId);
+        if (!record) {
+            console.warn(`[ProfitTracker] Cannot record result for unknown intent: ${intentId}`);
+            return;
+        }
+        record.success = success;
+        record.actualGasUsed = gasUsed ?? record.pricing.gasCost;
+        if (success) {
+            // Net Profit = Total Fee Collected - Actual Gas Spent
+            const totalFee = BigInt(record.pricing.totalFee);
+            const actualGas = BigInt(record.actualGasUsed);
+            record.netProfit = (totalFee - actualGas).toString();
+        }
+        else {
+            // Unsuccessful translates to 0 net revenue (with actual loss = gas wasted)
+            record.netProfit = "0";
+        }
+    }
+    /**
+     * Get aggregate statistics
+     */
+    getStats(periodMs) {
+        let totalProfit = 0n;
+        let totalGasCost = 0n;
+        let successCount = 0;
+        let failCount = 0;
+        const now = Date.now();
+        for (const record of this.records.values()) {
+            if (periodMs && now - record.timestamp > periodMs) {
+                continue;
+            }
+            if (record.success === true) {
+                successCount++;
+                totalProfit += BigInt(record.netProfit || "0");
+                totalGasCost += BigInt(record.actualGasUsed || "0");
+            }
+            else if (record.success === false) {
+                failCount++;
+            }
+        }
+        const totalAttempts = successCount + failCount;
+        const avgProfit = successCount > 0 ? (totalProfit / BigInt(successCount)).toString() : "0";
+        return {
+            totalProfit: totalProfit.toString(),
+            totalGasCost: totalGasCost.toString(),
+            successCount,
+            failCount,
+            avgProfit,
+            totalAttempts,
+        };
+    }
+    /**
+     * Get annualized ROI percentage based on capital deployed
+     */
+    getROI(capitalDeployed) {
+        const capital = BigInt(capitalDeployed);
+        if (capital === 0n)
+            return 0;
+        const stats = this.getStats();
+        if (stats.totalProfit === "0" || this.startedAt === null)
+            return 0;
+        // Safe precision: divide big-int profit by capital without converting
+        // both to float until we have the ratio (which is << 2^53 in practice)
+        const profitBn = BigInt(stats.totalProfit);
+        // Represent ratio as numerator/denominator pair, then convert to float
+        const ratioNumerator = Number(profitBn * 10000000n / capital); // 7 decimal places of room
+        const roiPeriod = ratioNumerator / 10_000_000;
+        // Use the tracked startedAt so we only iterate records once (in getStats)
+        const elapsedMs = Date.now() - this.startedAt;
+        if (elapsedMs === 0)
+            return 0;
+        const yearsElapsed = elapsedMs / (365 * 24 * 3600 * 1000);
+        if (yearsElapsed === 0)
+            return 0;
+        return (roiPeriod / yearsElapsed) * 100; // Returns percentage %
+    }
+}
+//# sourceMappingURL=profit-tracker.js.map

package/dist/solver/monitoring/profit-tracker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"profit-tracker.js","sourceRoot":"","sources":["../../../src/solver/monitoring/profit-tracker.ts"],"names":[],"mappings":"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"}

package/dist/solver/pricing/dynamic-pricing.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Dynamic Pricing
+ *
+ * Menyesuaikan fee multiplier berdasarkan kondisi inventory saat ini.
+ * Semakin langka inventory di chain tertentu, semakin tinggi harga yang dikenakan.
+ *
+ * TUJUAN:
+ *   - Mencegah pengurasan inventory satu chain secara cepat (flood protection)
+ *   - Mendorong rebalancing secara ekonomi: harga tinggi → solver rebalance lebih cepat
+ *   - Memberikan keunggulan kompetitif di kondisi surplus (harga lebih rendah = lebih sering menang)
+ *
+ * INVENTORY MULTIPLIER TABLE:
+ *   ≥ 80% capacity  → 0.8x  (surplus, bersaing aggressive)
+ *   50–79% capacity → 1.0x  (normal)
+ *   20–49% capacity → 1.5x  (low, mulai naikkan harga)
+ *   < 20% capacity  → 2.0x  (critical, hampir habis)
+ *
+ * FORMULA:
+ *   finalFee = baseFee * inventoryMultiplier
+ *
+ * NOTE: Multiplier diterapkan HANYA ke baseFee, bukan ke gasCost.
+ *       gasCost selalu tetap (reflek biaya aktual, bukan inventory state).
+ */
+import type { PricingConfig, PricingResult } from "../types/pricing";
+import type { SolverIntent } from "../types/intent";
+import type { ChainId } from "../../types/common";
+import type { InventoryManager } from "../inventory/inventory-manager";
+export declare class DynamicPricing {
+    private readonly config;
+    private readonly inventoryManager;
+    private readonly feeCalculator;
+    private readonly slippageCapture;
+    constructor(config: PricingConfig, inventoryManager: InventoryManager);
+    /**
+     * Hitung harga final untuk sebuah intent dengan dynamic multiplier.
+     *
+     * Langkah:
+     *   1. Extract params dari SolverIntent (amount, sourceChain, targetChain, maxSlippage)
+     *   2. Hitung base pricing via FeeCalculator
+     *   3. Apply inventory multiplier dari getInventoryMultiplier()
+     *   4. Re-compute totalFee dan solverProfit dengan nilai yang sudah di-adjust
+     *
+     * @param intent - SolverIntent yang akan di-price
+     * @returns PricingResult dengan multiplier sudah diterapkan
+     */
+    getPrice(intent: SolverIntent): PricingResult;
+    /**
+     * Tentukan inventory multiplier (sebagai number) berdasarkan kapasitas chain.
+     *
+     * "Kapasitas" didefinisikan sebagai proporsi balance chain ini terhadap total semua chain.
+     *   capacity = getBalance(chainId, token) / getTotalBalance(token)
+     *
+     * MULTIPLIER TIERS:
+     *   capacity >= 0.8  → 0.8  (surplus mode)
+     *   capacity >= 0.5  → 1.0  (normal)
+     *   capacity >= 0.2  → 1.5  (low inventory)
+     *   capacity <  0.2  → 2.0  (critical)
+     *
+     * @param chainId - Chain yang akan di-check inventory-nya
+     * @param amount  - Amount yang dibutuhkan (unused, tersedia untuk future use)
+     * @param token   - Token symbol untuk inventory check (default: "USDC")
+     * @returns Multiplier float (0.8 / 1.0 / 1.5 / 2.0)
+     */
+    getInventoryMultiplier(chainId: ChainId, amount: bigint, token?: string): number;
+    /**
+     * Cek apakah inventory di chain tertentu sudah terlalu kritis
+     * untuk menerima intent baru (reject outright, bukan hanya naikkan harga).
+     *
+     * Hard limit: inventory < 5% capacity (critical floor).
+     * Bahkan dengan multiplier 2.0x, menerima intent di kondisi ini
+     * berisiko menguras habis inventory.
+     *
+     * @param chainId - Chain yang akan di-check
+     * @param amount  - Amount intent yang diminta
+     * @param token   - Token symbol untuk inventory check (default: "USDC")
+     * @returns true jika harus di-reject, false jika aman diterima
+     */
+    shouldReject(chainId: ChainId, amount: bigint, token?: string): boolean;
+    /**
+     * Kembalikan tier (multiplierNum, multiplierDen, value) untuk chain berdasarkan kapasitas.
+     * Menggunakan BigInt fraction (num/den) untuk menghindari float precision loss
+     * saat diaplikasikan ke baseFee yang mungkin sangat besar (token 18 desimal).
+     */
+    private _getTierForChain;
+}
+//# sourceMappingURL=dynamic-pricing.d.ts.map

package/dist/solver/pricing/dynamic-pricing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dynamic-pricing.d.ts","sourceRoot":"","sources":["../../../src/solver/pricing/dynamic-pricing.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACrE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AACpD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gCAAgC,CAAC;AA6BvE,qBAAa,cAAc;IAKnB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,gBAAgB;IALrC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAgB;IAC9C,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAkB;gBAG7B,MAAM,EAAE,aAAa,EACrB,gBAAgB,EAAE,gBAAgB;IAUvD;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,MAAM,EAAE,YAAY,GAAG,aAAa;IAsD7C;;;;;;;;;;;;;;;;OAgBG;IACH,sBAAsB,CAAC,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,SAA0B,GAAG,MAAM;IAIjG;;;;;;;;;;;;OAYG;IACH,YAAY,CAAC,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,SAA0B,GAAG,OAAO;IAsBxF;;;;OAIG;IACH,OAAO,CAAC,gBAAgB;CAiB3B"}

package/dist/solver/pricing/dynamic-pricing.js

@@ -0,0 +1,189 @@
+/**
+ * Dynamic Pricing
+ *
+ * Menyesuaikan fee multiplier berdasarkan kondisi inventory saat ini.
+ * Semakin langka inventory di chain tertentu, semakin tinggi harga yang dikenakan.
+ *
+ * TUJUAN:
+ *   - Mencegah pengurasan inventory satu chain secara cepat (flood protection)
+ *   - Mendorong rebalancing secara ekonomi: harga tinggi → solver rebalance lebih cepat
+ *   - Memberikan keunggulan kompetitif di kondisi surplus (harga lebih rendah = lebih sering menang)
+ *
+ * INVENTORY MULTIPLIER TABLE:
+ *   ≥ 80% capacity  → 0.8x  (surplus, bersaing aggressive)
+ *   50–79% capacity → 1.0x  (normal)
+ *   20–49% capacity → 1.5x  (low, mulai naikkan harga)
+ *   < 20% capacity  → 2.0x  (critical, hampir habis)
+ *
+ * FORMULA:
+ *   finalFee = baseFee * inventoryMultiplier
+ *
+ * NOTE: Multiplier diterapkan HANYA ke baseFee, bukan ke gasCost.
+ *       gasCost selalu tetap (reflek biaya aktual, bukan inventory state).
+ */
+import { FeeCalculator } from "./fee-calculator";
+import { SlippageCapture } from "./slippage-capture";
+// ─────────────────────────────────────────────
+// Internal Helpers
+// ─────────────────────────────────────────────
+/**
+ * Inventory tier definitions.
+ * Each tier has a capacity threshold (inclusive lower bound) and a multiplier.
+ * Tiers are checked from highest to lowest.
+ *
+ * Multiplier is expressed as [numerator, denominator] to enable lossless BigInt math.
+ * e.g. 0.8x → [8, 10], 1.5x → [15, 10], 2.0x → [20, 10]
+ */
+const INVENTORY_TIERS = [
+    { threshold: 0.8, multiplierNum: 8n, multiplierDen: 10n, value: 0.8 },
+    { threshold: 0.5, multiplierNum: 10n, multiplierDen: 10n, value: 1.0 },
+    { threshold: 0.2, multiplierNum: 15n, multiplierDen: 10n, value: 1.5 },
+    { threshold: 0, multiplierNum: 20n, multiplierDen: 10n, value: 2.0 }, // critical fallback
+];
+/** Capacity below this triggers hard rejection regardless of price */
+const CRITICAL_CAPACITY_FLOOR = 0.05;
+/** Default settlement token for inventory checks */
+const DEFAULT_INVENTORY_TOKEN = "USDC";
+export class DynamicPricing {
+    config;
+    inventoryManager;
+    feeCalculator;
+    slippageCapture;
+    constructor(config, inventoryManager) {
+        this.config = config;
+        this.inventoryManager = inventoryManager;
+        this.feeCalculator = new FeeCalculator(config);
+        this.slippageCapture = new SlippageCapture(config);
+    }
+    // ─────────────────────────────────────────────
+    // Public API
+    // ─────────────────────────────────────────────
+    /**
+     * Hitung harga final untuk sebuah intent dengan dynamic multiplier.
+     *
+     * Langkah:
+     *   1. Extract params dari SolverIntent (amount, sourceChain, targetChain, maxSlippage)
+     *   2. Hitung base pricing via FeeCalculator
+     *   3. Apply inventory multiplier dari getInventoryMultiplier()
+     *   4. Re-compute totalFee dan solverProfit dengan nilai yang sudah di-adjust
+     *
+     * @param intent - SolverIntent yang akan di-price
+     * @returns PricingResult dengan multiplier sudah diterapkan
+     */
+    getPrice(intent) {
+        // 1. Extract intent parameters
+        const params = intent.parsedIntent.parameters;
+        if (intent.parsedIntent.intentType !== "bridge") {
+            throw new Error(`Unsupported intent type for pricing: ${intent.parsedIntent.intentType}`);
+        }
+        if (!params.inputAmount || !params.inputToken || !params.sourceChain || !params.targetChain) {
+            throw new Error("Invalid bridge intent: missing required parameters");
+        }
+        const amount = BigInt(params.inputAmount);
+        const sourceChain = Number(params.sourceChain);
+        const targetChain = Number(params.targetChain);
+        const maxSlippageBps = intent.parsedIntent.constraints.maxSlippage ?? 100;
+        // Use the intent's token symbol for inventory checks (default to USDC for stablecoins)
+        const token = typeof params.inputToken === "string" ? params.inputToken : DEFAULT_INVENTORY_TOKEN;
+        // 2. Get base fees from FeeCalculator
+        const rawPricing = this.feeCalculator.calculate({
+            amount,
+            sourceChain,
+            targetChain,
+            token,
+            maxSlippageBps,
+        });
+        // 3. Apply inventory multiplier using BigInt arithmetic (no float precision loss)
+        const { multiplierNum, multiplierDen } = this._getTierForChain(targetChain, token);
+        const baseFeeVal = BigInt(rawPricing.baseFee);
+        const adjustedBaseFee = (baseFeeVal * multiplierNum) / multiplierDen;
+        // 4. Reconstruct totals with adjusted base fee
+        const gasCost = BigInt(rawPricing.gasCost);
+        const slippageCapture = BigInt(rawPricing.slippageCapture);
+        const totalFee = adjustedBaseFee + gasCost + slippageCapture;
+        let userReceives = amount - totalFee;
+        if (userReceives < 0n)
+            userReceives = 0n;
+        const solverProfit = totalFee - gasCost;
+        return {
+            baseFee: adjustedBaseFee.toString(),
+            gasCost: gasCost.toString(),
+            slippageCapture: slippageCapture.toString(),
+            totalFee: totalFee.toString(),
+            userPays: amount.toString(),
+            userReceives: userReceives.toString(),
+            solverProfit: solverProfit.toString(),
+        };
+    }
+    /**
+     * Tentukan inventory multiplier (sebagai number) berdasarkan kapasitas chain.
+     *
+     * "Kapasitas" didefinisikan sebagai proporsi balance chain ini terhadap total semua chain.
+     *   capacity = getBalance(chainId, token) / getTotalBalance(token)
+     *
+     * MULTIPLIER TIERS:
+     *   capacity >= 0.8  → 0.8  (surplus mode)
+     *   capacity >= 0.5  → 1.0  (normal)
+     *   capacity >= 0.2  → 1.5  (low inventory)
+     *   capacity <  0.2  → 2.0  (critical)
+     *
+     * @param chainId - Chain yang akan di-check inventory-nya
+     * @param amount  - Amount yang dibutuhkan (unused, tersedia untuk future use)
+     * @param token   - Token symbol untuk inventory check (default: "USDC")
+     * @returns Multiplier float (0.8 / 1.0 / 1.5 / 2.0)
+     */
+    getInventoryMultiplier(chainId, amount, token = DEFAULT_INVENTORY_TOKEN) {
+        return this._getTierForChain(chainId, token).value;
+    }
+    /**
+     * Cek apakah inventory di chain tertentu sudah terlalu kritis
+     * untuk menerima intent baru (reject outright, bukan hanya naikkan harga).
+     *
+     * Hard limit: inventory < 5% capacity (critical floor).
+     * Bahkan dengan multiplier 2.0x, menerima intent di kondisi ini
+     * berisiko menguras habis inventory.
+     *
+     * @param chainId - Chain yang akan di-check
+     * @param amount  - Amount intent yang diminta
+     * @param token   - Token symbol untuk inventory check (default: "USDC")
+     * @returns true jika harus di-reject, false jika aman diterima
+     */
+    shouldReject(chainId, amount, token = DEFAULT_INVENTORY_TOKEN) {
+        // 1. Check strict availability first (includes reserve check)
+        if (!this.inventoryManager.canFulfill(chainId, token, amount)) {
+            return true;
+        }
+        // 2. Check hard capacity floor
+        const current = this.inventoryManager.getBalance(chainId, token);
+        const total = this.inventoryManager.getTotalBalance(token);
+        if (total === 0n)
+            return true; // Should be caught by canFulfill, but safety guard
+        const capacity = Number(current) / Number(total);
+        // Reject if capacity is critically low to force rebalancing before draining chain
+        return capacity < CRITICAL_CAPACITY_FLOOR;
+    }
+    // ─────────────────────────────────────────────
+    // Private Helpers
+    // ─────────────────────────────────────────────
+    /**
+     * Kembalikan tier (multiplierNum, multiplierDen, value) untuk chain berdasarkan kapasitas.
+     * Menggunakan BigInt fraction (num/den) untuk menghindari float precision loss
+     * saat diaplikasikan ke baseFee yang mungkin sangat besar (token 18 desimal).
+     */
+    _getTierForChain(chainId, token) {
+        const current = this.inventoryManager.getBalance(chainId, token);
+        const total = this.inventoryManager.getTotalBalance(token);
+        // No inventory anywhere → critical tier
+        if (total === 0n)
+            return INVENTORY_TIERS[INVENTORY_TIERS.length - 1];
+        const capacity = Number(current) / Number(total);
+        // Find first matching tier (ordered highest threshold → lowest)
+        for (const tier of INVENTORY_TIERS) {
+            if (capacity >= tier.threshold)
+                return tier;
+        }
+        // Should never reach here as last tier has threshold 0
+        return INVENTORY_TIERS[INVENTORY_TIERS.length - 1];
+    }
+}
+//# sourceMappingURL=dynamic-pricing.js.map

package/dist/solver/pricing/dynamic-pricing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dynamic-pricing.js","sourceRoot":"","sources":["../../../src/solver/pricing/dynamic-pricing.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAMH,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACjD,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAErD,gDAAgD;AAChD,mBAAmB;AACnB,gDAAgD;AAEhD;;;;;;;GAOG;AACH,MAAM,eAAe,GAA8F;IAC/G,EAAE,SAAS,EAAE,GAAG,EAAE,aAAa,EAAE,EAAE,EAAE,aAAa,EAAE,GAAG,EAAE,KAAK,EAAE,GAAG,EAAE;IACrE,EAAE,SAAS,EAAE,GAAG,EAAE,aAAa,EAAE,GAAG,EAAE,aAAa,EAAE,GAAG,EAAE,KAAK,EAAE,GAAG,EAAE;IACtE,EAAE,SAAS,EAAE,GAAG,EAAE,aAAa,EAAE,GAAG,EAAE,aAAa,EAAE,GAAG,EAAE,KAAK,EAAE,GAAG,EAAE;IACtE,EAAE,SAAS,EAAE,CAAC,EAAE,aAAa,EAAE,GAAG,EAAE,aAAa,EAAE,GAAG,EAAE,KAAK,EAAE,GAAG,EAAE,EAAE,oBAAoB;CAC7F,CAAC;AAEF,sEAAsE;AACtE,MAAM,uBAAuB,GAAG,IAAI,CAAC;AAErC,oDAAoD;AACpD,MAAM,uBAAuB,GAAG,MAAM,CAAC;AAEvC,MAAM,OAAO,cAAc;IAKF;IACA;IALJ,aAAa,CAAgB;IAC7B,eAAe,CAAkB;IAElD,YACqB,MAAqB,EACrB,gBAAkC;QADlC,WAAM,GAAN,MAAM,CAAe;QACrB,qBAAgB,GAAhB,gBAAgB,CAAkB;QAEnD,IAAI,CAAC,aAAa,GAAG,IAAI,aAAa,CAAC,MAAM,CAAC,CAAC;QAC/C,IAAI,CAAC,eAAe,GAAG,IAAI,eAAe,CAAC,MAAM,CAAC,CAAC;IACvD,CAAC;IAED,gDAAgD;IAChD,aAAa;IACb,gDAAgD;IAEhD;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,MAAoB;QACzB,+BAA+B;QAC/B,MAAM,MAAM,GAAG,MAAM,CAAC,YAAY,CAAC,UAAU,CAAC;QAC9C,IAAI,MAAM,CAAC,YAAY,CAAC,UAAU,KAAK,QAAQ,EAAE,CAAC;YAC9C,MAAM,IAAI,KAAK,CAAC,wCAAwC,MAAM,CAAC,YAAY,CAAC,UAAU,EAAE,CAAC,CAAC;QAC9F,CAAC;QAED,IAAI,CAAC,MAAM,CAAC,WAAW,IAAI,CAAC,MAAM,CAAC,UAAU,IAAI,CAAC,MAAM,CAAC,WAAW,IAAI,CAAC,MAAM,CAAC,WAAW,EAAE,CAAC;YAC1F,MAAM,IAAI,KAAK,CAAC,oDAAoD,CAAC,CAAC;QAC1E,CAAC;QAED,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC;QAC1C,MAAM,WAAW,GAAG,MAAM,CAAC,MAAM,CAAC,WAAW,CAAY,CAAC;QAC1D,MAAM,WAAW,GAAG,MAAM,CAAC,MAAM,CAAC,WAAW,CAAY,CAAC;QAC1D,MAAM,cAAc,GAAG,MAAM,CAAC,YAAY,CAAC,WAAW,CAAC,WAAW,IAAI,GAAG,CAAC;QAC1E,uFAAuF;QACvF,MAAM,KAAK,GAAG,OAAO,MAAM,CAAC,UAAU,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,CAAC,uBAAuB,CAAC;QAElG,sCAAsC;QACtC,MAAM,UAAU,GAAG,IAAI,CAAC,aAAa,CAAC,SAAS,CAAC;YAC5C,MAAM;YACN,WAAW;YACX,WAAW;YACX,KAAK;YACL,cAAc;SACjB,CAAC,CAAC;QAEH,kFAAkF;QAClF,MAAM,EAAE,aAAa,EAAE,aAAa,EAAE,GAAG,IAAI,CAAC,gBAAgB,CAAC,WAAW,EAAE,KAAK,CAAC,CAAC;QACnF,MAAM,UAAU,GAAG,MAAM,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC;QAC9C,MAAM,eAAe,GAAG,CAAC,UAAU,GAAG,aAAa,CAAC,GAAG,aAAa,CAAC;QAErE,+CAA+C;QAC/C,MAAM,OAAO,GAAG,MAAM,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC;QAC3C,MAAM,eAAe,GAAG,MAAM,CAAC,UAAU,CAAC,eAAe,CAAC,CAAC;QAE3D,MAAM,QAAQ,GAAG,eAAe,GAAG,OAAO,GAAG,eAAe,CAAC;QAE7D,IAAI,YAAY,GAAG,MAAM,GAAG,QAAQ,CAAC;QACrC,IAAI,YAAY,GAAG,EAAE;YAAE,YAAY,GAAG,EAAE,CAAC;QAEzC,MAAM,YAAY,GAAG,QAAQ,GAAG,OAAO,CAAC;QAExC,OAAO;YACH,OAAO,EAAE,eAAe,CAAC,QAAQ,EAAE;YACnC,OAAO,EAAE,OAAO,CAAC,QAAQ,EAAE;YAC3B,eAAe,EAAE,eAAe,CAAC,QAAQ,EAAE;YAC3C,QAAQ,EAAE,QAAQ,CAAC,QAAQ,EAAE;YAC7B,QAAQ,EAAE,MAAM,CAAC,QAAQ,EAAE;YAC3B,YAAY,EAAE,YAAY,CAAC,QAAQ,EAAE;YACrC,YAAY,EAAE,YAAY,CAAC,QAAQ,EAAE;SACxC,CAAC;IACN,CAAC;IAED;;;;;;;;;;;;;;;;OAgBG;IACH,sBAAsB,CAAC,OAAgB,EAAE,MAAc,EAAE,KAAK,GAAG,uBAAuB;QACpF,OAAO,IAAI,CAAC,gBAAgB,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC,KAAK,CAAC;IACvD,CAAC;IAED;;;;;;;;;;;;OAYG;IACH,YAAY,CAAC,OAAgB,EAAE,MAAc,EAAE,KAAK,GAAG,uBAAuB;QAC1E,8DAA8D;QAC9D,IAAI,CAAC,IAAI,CAAC,gBAAgB,CAAC,UAAU,CAAC,OAAO,EAAE,KAAK,EAAE,MAAM,CAAC,EAAE,CAAC;YAC5D,OAAO,IAAI,CAAC;QAChB,CAAC;QAED,+BAA+B;QAC/B,MAAM,OAAO,GAAG,IAAI,CAAC,gBAAgB,CAAC,UAAU,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;QACjE,MAAM,KAAK,GAAG,IAAI,CAAC,gBAAgB,CAAC,eAAe,CAAC,KAAK,CAAC,CAAC;QAE3D,IAAI,KAAK,KAAK,EAAE;YAAE,OAAO,IAAI,CAAC,CAAC,mDAAmD;QAElF,MAAM,QAAQ,GAAG,MAAM,CAAC,OAAO,CAAC,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;QAEjD,kFAAkF;QAClF,OAAO,QAAQ,GAAG,uBAAuB,CAAC;IAC9C,CAAC;IAED,gDAAgD;IAChD,kBAAkB;IAClB,gDAAgD;IAEhD;;;;OAIG;IACK,gBAAgB,CAAC,OAAgB,EAAE,KAAa;QACpD,MAAM,OAAO,GAAG,IAAI,CAAC,gBAAgB,CAAC,UAAU,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;QACjE,MAAM,KAAK,GAAG,IAAI,CAAC,gBAAgB,CAAC,eAAe,CAAC,KAAK,CAAC,CAAC;QAE3D,wCAAwC;QACxC,IAAI,KAAK,KAAK,EAAE;YAAE,OAAO,eAAe,CAAC,eAAe,CAAC,MAAM,GAAG,CAAC,CAAE,CAAC;QAEtE,MAAM,QAAQ,GAAG,MAAM,CAAC,OAAO,CAAC,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;QAEjD,gEAAgE;QAChE,KAAK,MAAM,IAAI,IAAI,eAAe,EAAE,CAAC;YACjC,IAAI,QAAQ,IAAI,IAAI,CAAC,SAAS;gBAAE,OAAO,IAAI,CAAC;QAChD,CAAC;QAED,uDAAuD;QACvD,OAAO,eAAe,CAAC,eAAe,CAAC,MAAM,GAAG,CAAC,CAAE,CAAC;IACxD,CAAC;CACJ"}

package/dist/solver/pricing/fee-calculator.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Fee Calculator
+ *
+ * Menghitung total biaya yang dikenakan solver kepada user.
+ * Fee terdiri dari tiga komponen:
+ *
+ *   1. BASE FEE      — persentase dari amount (default 0.5%)
+ *   2. GAS COST      — estimasi biaya gas dalam token (USDC)
+ *   3. SLIPPAGE CAPTURE — bagian dari max slippage user yang solver ambil
+ *
+ * FORMULA:
+ *   totalFee = baseFee + gasCost + slippageCapture
+ *   userReceives = amount - totalFee
+ *   solverProfit = totalFee - gasCost
+ *
+ * EXAMPLE (1000 USDC, ETH→Polygon):
+ *   baseFee        = 5 USDC  (0.5%)
+ *   gasCost        = 3 USDC  (ETH mainnet involved)
+ *   slippageCapture = 5 USDC (50% of 1% max slippage on 1000 USDC)
+ *   totalFee       = 13 USDC
+ *   solverProfit   = 10 USDC
+ */
+import type { PricingConfig, PricingResult } from "../types/pricing";
+import type { ChainId } from "../../types/common";
+/**
+ * Parameters untuk kalkulasi fee tunggal.
+ */
+export interface FeeCalculationParams {
+    /** Amount yang di-bridge dalam token smallest unit (e.g., 1000 USDC = 1_000_000_000n untuk 6 decimals) */
+    amount: bigint;
+    /** Chain tempat user menyimpan dana (source) */
+    sourceChain: ChainId;
+    /** Chain tujuan pengiriman (target) */
+    targetChain: ChainId;
+    /** Token symbol (e.g., "USDC") */
+    token: string;
+    /** Max slippage yang diizinkan user, dalam basis points (100 = 1%) */
+    maxSlippageBps: number;
+    /** Jumlah desimal token (6 untuk USDC, 18 untuk ETH) */
+    tokenDecimals?: number;
+}
+export declare class FeeCalculator {
+    private readonly config;
+    private readonly slippageCapture;
+    constructor(config: PricingConfig);
+    /**
+     * Hitung full fee breakdown untuk sebuah bridge intent.
+     *
+     * Langkah:
+     *   1. Hitung base fee dari `amount * baseFeePercent`, clamp ke [minFee, maxFee]
+     *   2. Estimasi gas cost via `estimateGasCost()`
+     *   3. Hitung slippage capture via `SlippageCapture.calculate()`
+     *   4. Gabungkan menjadi PricingResult
+     *
+     * @param params - FeeCalculationParams
+     * @returns PricingResult dengan semua fee breakdown
+     */
+    calculate(params: FeeCalculationParams): PricingResult;
+    /**
+     * Hitung base fee saja dari sebuah amount.
+     *
+     * Berguna untuk quick check profitabilitas tanpa full pricing.
+     *
+     * @param amount       - Amount dalam token's smallest unit
+     * @param tokenDecimals - Jumlah desimal token (default 6 untuk USDC)
+     * @returns Base fee dalam token's smallest unit (bigint)
+     */
+    calculateBaseFee(amount: bigint, tokenDecimals?: number): bigint;
+    /**
+     * Estimasi biaya gas dalam token equivalent (USDC).
+     *
+     * Logika:
+     *   - Cross-chain (sourceChain !== targetChain) jauh lebih mahal dari single-chain
+     *   - Ethereum mainnet memiliki gas cost tertinggi karena konsensus proof-of-stake
+     *     dan tingginya demand block space
+     *   - L2 (Polygon, Arbitrum) jauh lebih murah
+     *
+     * Gunakan hardcoded baseline yang akan diganti real gas oracle di Phase I.
+     *
+     * @param sourceChain - Chain ID asal
+     * @param targetChain - Chain ID tujuan (opsional, untuk cross-chain estimate)
+     * @returns Gas cost estimasi dalam USDC (6 decimals, bigint)
+     */
+    estimateGasCost(sourceChain: ChainId, targetChain?: ChainId): bigint;
+    /**
+     * Cek apakah sebuah intent worth solving (profitable setelah fee).
+     *
+     * Intent tidak worth solving jika:
+     *   - Amount terlalu kecil sehingga fee > amount
+     *   - Cross-chain gas cost > baseFee (loss scenario)
+     *
+     * Note: Slippage capture diabaikan di sini (conservative check).
+     *
+     * @param amount      - Amount dalam token's smallest unit
+     * @param sourceChain - Chain ID asal
+     * @param targetChain - Chain ID tujuan
+     * @returns true jika worth solving, false jika tidak
+     */
+    isWorthSolving(amount: bigint, sourceChain: ChainId, targetChain: ChainId): boolean;
+}
+//# sourceMappingURL=fee-calculator.d.ts.map

package/dist/solver/pricing/fee-calculator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fee-calculator.d.ts","sourceRoot":"","sources":["../../../src/solver/pricing/fee-calculator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACrE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAMlD;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACjC,0GAA0G;IAC1G,MAAM,EAAE,MAAM,CAAC;IAEf,gDAAgD;IAChD,WAAW,EAAE,OAAO,CAAC;IAErB,uCAAuC;IACvC,WAAW,EAAE,OAAO,CAAC;IAErB,kCAAkC;IAClC,KAAK,EAAE,MAAM,CAAC;IAEd,sEAAsE;IACtE,cAAc,EAAE,MAAM,CAAC;IAEvB,wDAAwD;IACxD,aAAa,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,qBAAa,aAAa;IAIlB,OAAO,CAAC,QAAQ,CAAC,MAAM;IAH3B,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAkB;gBAG7B,MAAM,EAAE,aAAa;IAS1C;;;;;;;;;;;OAWG;IACH,SAAS,CAAC,MAAM,EAAE,oBAAoB,GAAG,aAAa;IA8BtD;;;;;;;;OAQG;IACH,gBAAgB,CAAC,MAAM,EAAE,MAAM,EAAE,aAAa,SAAI,GAAG,MAAM;IAmB3D;;;;;;;;;;;;;;OAcG;IACH,eAAe,CAAC,WAAW,EAAE,OAAO,EAAE,WAAW,CAAC,EAAE,OAAO,GAAG,MAAM;IAmBpE;;;;;;;;;;;;;OAaG;IACH,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,OAAO,EAAE,WAAW,EAAE,OAAO,GAAG,OAAO;CAStF"}