@gvnrdao/dh-lit-actions 0.0.61 → 0.0.63

package/pkg-dist/src/modules/vault-balance.module.d.ts

@@ -0,0 +1,172 @@
+/**
+ * Vault Balance Module - Super Module for Trusted Balance Calculation
+ *
+ * Combines Bitcoin network data with smart contract state to calculate
+ * the "trusted balance" - the amount available for new authorizations.
+ *
+ * Formula: Available Balance = Total UTXOs - Authorized Spends
+ *
+ * This is the primary source of truth for determining if a new spending
+ * authorization can be created for a given position.
+ */
+import { AuthorizedSpend, UTXO, VaultBalanceConfig, VaultBalanceResult } from "../interfaces/chunks/vault-balance.i";
+import { IVaultBalance } from "../interfaces/chunks/vault-balance-module.i";
+/**
+ * Vault Balance Module
+ *
+ * This module is the "super module" that combines:
+ * 1. Bitcoin network data (UTXOs from bitcoin-data-provider)
+ * 2. Smart contract state (authorized spends from contract)
+ *
+ * To produce: Trusted Balance = Total - Authorized
+ *
+ * DESIGN NOTES:
+ *
+ * 1. Change Output Handling:
+ *    When a UTXO is spent, the change output will have a DIFFERENT txid.
+ *    This means we don't need special logic for change - it appears as a new UTXO.
+ *    The old UTXO (original deposit) will be gone from Bitcoin queries.
+ *
+ * 2. Authorization is Commitment:
+ *    Any UTXO in the AuthorizedSpend array is considered committed/consumed.
+ *    Once authorized, it's the user's responsibility to sign and broadcast.
+ *    If they don't, that's their problem - not the ecosystem's concern.
+ *
+ * 3. Security Model - Dual Source of Truth:
+ *    - Bitcoin Network: What UTXOs actually exist
+ *    - Smart Contract: What UTXOs are authorized to be spent
+ *    - Available Balance = Total UTXOs - Authorized UTXOs
+ *
+ *    This prevents double-spending by ensuring the same UTXO cannot be
+ *    authorized twice. The contract's isAuthorizedSpend mapping enforces this.
+ *
+ * 4. Race Condition Protection:
+ *    The FAFO (First Actor Fails Others) model protects against concurrent
+ *    authorization attempts via state hash commitment in quantum time windows.
+ *    This module provides the trusted balance INPUT to that authorization process.
+ *
+ * 5. UTXO Matching:
+ *    We match authorized spends to UTXOs by (txid, vout) pair.
+ *    A UTXO is available if it exists in Bitcoin but NOT in authorized spends.
+ *
+ * 6. Edge Cases:
+ *    - UTXO authorized but not yet spent: Appears in Bitcoin, appears in contract
+ *    - UTXO spent: Doesn't appear in Bitcoin, may still appear in contract
+ *    - New deposit: Appears in Bitcoin, doesn't appear in contract
+ */
+export declare class VaultBalanceModule implements IVaultBalance {
+    private config;
+    private bitcoinProvider;
+    constructor(config: VaultBalanceConfig);
+    /**
+     * Calculate trusted balance for a position
+     *
+     * This is the main entry point for determining available balance.
+     *
+     * CRITICAL: Validates that all authorized spends have been properly broadcasted
+     * to Bitcoin network with sufficient confirmations. Throws errors if:
+     * 1. Authorized transaction not found on network (not broadcasted)
+     * 2. Authorized transaction has insufficient confirmations (network updating)
+     *
+     * @param positionId - The position ID to check
+     * @param vaultAddress - Bitcoin address of the vault
+     * @returns Complete breakdown of vault balance
+     * @throws Error if authorized spends are in invalid state
+     */
+    calculateTrustedBalance(positionId: string, vaultAddress: string): Promise<VaultBalanceResult>;
+    /**
+     * Get just the trusted balance amount
+     *
+     * Convenience method when you only need the number.
+     *
+     * @param positionId - The position ID to check
+     * @param vaultAddress - Bitcoin address of the vault
+     * @returns Available balance in satoshis
+     */
+    getTrustedBalance(positionId: string, vaultAddress: string): Promise<bigint>;
+    /**
+     * Get available UTXOs that can be used for new authorizations
+     *
+     * This is useful when you need to select specific UTXOs for authorization.
+     *
+     * @param positionId - The position ID to check
+     * @param vaultAddress - Bitcoin address of the vault
+     * @returns Array of available UTXOs
+     */
+    getAvailableUTXOs(positionId: string, vaultAddress: string): Promise<UTXO[]>;
+    /**
+     * Check if a specific UTXO is available for authorization
+     *
+     * @param positionId - The position ID to check
+     * @param vaultAddress - Bitcoin address of the vault
+     * @param txid - Transaction ID of the UTXO
+     * @param vout - Output index of the UTXO
+     * @returns True if UTXO is available, false otherwise
+     */
+    isUTXOAvailable(positionId: string, vaultAddress: string, txid: string, vout: number): Promise<boolean>;
+    /**
+     * Check if a UTXO is authorized (appears in authorized spends)
+     *
+     * @param utxo - The UTXO to check
+     * @param authorizedSpends - List of authorized spends from contract
+     * @returns True if UTXO is authorized, false otherwise
+     */
+    private isUTXOAuthorized;
+    /**
+     * Query smart contract for authorized spends
+     *
+     * Calls the contract's getAuthorizedSpends(positionId) view function
+     * to retrieve all authorized Bitcoin spends for this position.
+     *
+     * Contract struct AuthorizedSpend:
+     * - txid: string
+     * - vout: uint32
+     * - satoshis: uint256
+     * - authorizedAt: uint256 (timestamp)
+     *
+     * @param positionId - The position ID to query
+     * @returns Array of authorized spends for this position
+     */
+    protected getAuthorizedSpendsFromContract(positionId: string): Promise<AuthorizedSpend[]>;
+}
+/**
+ * Factory function to create VaultBalanceModule instance
+ *
+ * @param config - Configuration for the module
+ * @returns VaultBalanceModule instance
+ */
+export declare function createVaultBalanceModule(config: VaultBalanceConfig): VaultBalanceModule;
+/**
+ * USAGE EXAMPLE:
+ *
+ * ```typescript
+ * import { createVaultBalanceModule } from './vault-balance.module';
+ * import { BitcoinDataProvider } from './bitcoin-data-provider.module';
+ *
+ * const bitcoinProvider = new BitcoinDataProvider({
+ *   providerUrl: 'https://blockstream.info/testnet/api'
+ * });
+ *
+ * const vaultBalance = createVaultBalanceModule({
+ *   contractAddress: '0x...',
+ *   chain: 'sepolia',
+ *   bitcoinProvider,
+ *   minConfirmations: 6
+ * });
+ *
+ * // Get complete balance breakdown
+ * const result = await vaultBalance.calculateTrustedBalance(
+ *   'position123',
+ *   'tb1q...'
+ * );
+ *
+ * console.log('Total Balance:', result.totalBalance, 'sats');
+ * console.log('Authorized Balance:', result.authorizedBalance, 'sats');
+ * console.log('Available Balance:', result.availableBalance, 'sats');
+ *
+ * // Or just get the available amount
+ * const available = await vaultBalance.getTrustedBalance('position123', 'tb1q...');
+ * console.log('Can authorize:', available, 'sats');
+ * ```
+ */
+//# sourceMappingURL=vault-balance.module.d.ts.map

package/pkg-dist/src/modules/vault-balance.module.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vault-balance.module.d.ts","sourceRoot":"","sources":["../../../src/modules/vault-balance.module.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EACL,eAAe,EACf,IAAI,EAEJ,kBAAkB,EAClB,kBAAkB,EACnB,MAAM,sCAAsC,CAAC;AAE9C,OAAO,EAAE,aAAa,EAAE,MAAM,6CAA6C,CAAC;AAG5E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,qBAAa,kBAAmB,YAAW,aAAa;IACtD,OAAO,CAAC,MAAM,CAAqB;IACnC,OAAO,CAAC,eAAe,CAAuB;gBAElC,MAAM,EAAE,kBAAkB;IAKtC;;;;;;;;;;;;;;OAcG;IACG,uBAAuB,CAC3B,UAAU,EAAE,MAAM,EAClB,YAAY,EAAE,MAAM,GACnB,OAAO,CAAC,kBAAkB,CAAC;IA6E9B;;;;;;;;OAQG;IACG,iBAAiB,CACrB,UAAU,EAAE,MAAM,EAClB,YAAY,EAAE,MAAM,GACnB,OAAO,CAAC,MAAM,CAAC;IAKlB;;;;;;;;OAQG;IACG,iBAAiB,CACrB,UAAU,EAAE,MAAM,EAClB,YAAY,EAAE,MAAM,GACnB,OAAO,CAAC,IAAI,EAAE,CAAC;IAKlB;;;;;;;;OAQG;IACG,eAAe,CACnB,UAAU,EAAE,MAAM,EAClB,YAAY,EAAE,MAAM,EACpB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,OAAO,CAAC;IAUnB;;;;;;OAMG;IACH,OAAO,CAAC,gBAAgB;IASxB;;;;;;;;;;;;;;OAcG;cACa,+BAA+B,CAC7C,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,eAAe,EAAE,CAAC;CA8F9B;AAED;;;;;GAKG;AACH,wBAAgB,wBAAwB,CACtC,MAAM,EAAE,kBAAkB,GACzB,kBAAkB,CAEpB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG"}

package/pkg-dist/src/modules/vault-balance.module.js

@@ -0,0 +1,318 @@
+"use strict";
+/**
+ * Vault Balance Module - Super Module for Trusted Balance Calculation
+ *
+ * Combines Bitcoin network data with smart contract state to calculate
+ * the "trusted balance" - the amount available for new authorizations.
+ *
+ * Formula: Available Balance = Total UTXOs - Authorized Spends
+ *
+ * This is the primary source of truth for determining if a new spending
+ * authorization can be created for a given position.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VaultBalanceModule = void 0;
+exports.createVaultBalanceModule = createVaultBalanceModule;
+/**
+ * Vault Balance Module
+ *
+ * This module is the "super module" that combines:
+ * 1. Bitcoin network data (UTXOs from bitcoin-data-provider)
+ * 2. Smart contract state (authorized spends from contract)
+ *
+ * To produce: Trusted Balance = Total - Authorized
+ *
+ * DESIGN NOTES:
+ *
+ * 1. Change Output Handling:
+ *    When a UTXO is spent, the change output will have a DIFFERENT txid.
+ *    This means we don't need special logic for change - it appears as a new UTXO.
+ *    The old UTXO (original deposit) will be gone from Bitcoin queries.
+ *
+ * 2. Authorization is Commitment:
+ *    Any UTXO in the AuthorizedSpend array is considered committed/consumed.
+ *    Once authorized, it's the user's responsibility to sign and broadcast.
+ *    If they don't, that's their problem - not the ecosystem's concern.
+ *
+ * 3. Security Model - Dual Source of Truth:
+ *    - Bitcoin Network: What UTXOs actually exist
+ *    - Smart Contract: What UTXOs are authorized to be spent
+ *    - Available Balance = Total UTXOs - Authorized UTXOs
+ *
+ *    This prevents double-spending by ensuring the same UTXO cannot be
+ *    authorized twice. The contract's isAuthorizedSpend mapping enforces this.
+ *
+ * 4. Race Condition Protection:
+ *    The FAFO (First Actor Fails Others) model protects against concurrent
+ *    authorization attempts via state hash commitment in quantum time windows.
+ *    This module provides the trusted balance INPUT to that authorization process.
+ *
+ * 5. UTXO Matching:
+ *    We match authorized spends to UTXOs by (txid, vout) pair.
+ *    A UTXO is available if it exists in Bitcoin but NOT in authorized spends.
+ *
+ * 6. Edge Cases:
+ *    - UTXO authorized but not yet spent: Appears in Bitcoin, appears in contract
+ *    - UTXO spent: Doesn't appear in Bitcoin, may still appear in contract
+ *    - New deposit: Appears in Bitcoin, doesn't appear in contract
+ */
+class VaultBalanceModule {
+    constructor(config) {
+        this.config = config;
+        this.bitcoinProvider = config.bitcoinProvider;
+    }
+    /**
+     * Calculate trusted balance for a position
+     *
+     * This is the main entry point for determining available balance.
+     *
+     * CRITICAL: Validates that all authorized spends have been properly broadcasted
+     * to Bitcoin network with sufficient confirmations. Throws errors if:
+     * 1. Authorized transaction not found on network (not broadcasted)
+     * 2. Authorized transaction has insufficient confirmations (network updating)
+     *
+     * @param positionId - The position ID to check
+     * @param vaultAddress - Bitcoin address of the vault
+     * @returns Complete breakdown of vault balance
+     * @throws Error if authorized spends are in invalid state
+     */
+    async calculateTrustedBalance(positionId, vaultAddress) {
+        const minConfirmations = this.config.minConfirmations || 6;
+        // 1. Get all UTXOs from Bitcoin network
+        const utxoSet = await this.bitcoinProvider.getUTXOSet(vaultAddress, minConfirmations);
+        // 2. Get authorized spends from smart contract
+        const authorizedSpends = await this.getAuthorizedSpendsFromContract(positionId);
+        // 3. CRITICAL: Validate each authorized spend state
+        // For each authorized spend, check if UTXO still exists as unspent
+        for (const spend of authorizedSpends) {
+            const utxoStillExists = utxoSet.utxos.some((utxo) => utxo.txid === spend.txid && utxo.vout === spend.vout);
+            if (utxoStillExists) {
+                // ERROR B: UTXO authorized in contract but still unspent on Bitcoin network
+                // This means SDK authorized but never signed/broadcasted the spending transaction
+                throw new Error(`Authorized UTXO ${spend.txid}:${spend.vout} not yet spent. ` +
+                    `Transaction was authorized in smart contract but not signed and broadcasted to Bitcoin network. ` +
+                    `Complete the transaction by signing and broadcasting it.`);
+            }
+            // UTXO no longer exists as unspent (it's been spent)
+            // This is expected - now we verify the spending transaction has enough confirmations
+            // Note: spend.txid refers to the INPUT UTXO, not the spending transaction
+            // We cannot validate spending transaction confirmations without storing its txid
+            // For now, we trust that if UTXO doesn't exist, it's been properly spent
+            // TODO: Consider adding spendingTxid to AuthorizedSpend for full validation
+        }
+        // 4. Calculate authorized balance (sum of all authorized spends)
+        const authorizedBalance = authorizedSpends.reduce((sum, spend) => sum + spend.satoshis, 0n);
+        // 5. Filter out UTXOs that are authorized (not available)
+        // Note: After validation above, authorized UTXOs should NOT appear in utxoSet
+        // But we filter anyway for safety
+        const availableUTXOs = utxoSet.utxos.filter((utxo) => !this.isUTXOAuthorized(utxo, authorizedSpends));
+        // 6. Calculate available balance
+        const availableBalance = availableUTXOs.reduce((sum, utxo) => sum + utxo.satoshis, 0n);
+        return {
+            // Total from Bitcoin
+            totalUTXOs: utxoSet.utxos,
+            totalBalance: utxoSet.totalBalance,
+            // Authorized from Contract
+            authorizedUTXOs: authorizedSpends,
+            authorizedBalance,
+            // Available = Total - Authorized (THIS IS THE TRUSTED BALANCE)
+            availableUTXOs,
+            availableBalance,
+            // Metadata
+            vaultAddress,
+            positionId,
+            timestamp: Date.now(),
+        };
+    }
+    /**
+     * Get just the trusted balance amount
+     *
+     * Convenience method when you only need the number.
+     *
+     * @param positionId - The position ID to check
+     * @param vaultAddress - Bitcoin address of the vault
+     * @returns Available balance in satoshis
+     */
+    async getTrustedBalance(positionId, vaultAddress) {
+        const result = await this.calculateTrustedBalance(positionId, vaultAddress);
+        return result.availableBalance;
+    }
+    /**
+     * Get available UTXOs that can be used for new authorizations
+     *
+     * This is useful when you need to select specific UTXOs for authorization.
+     *
+     * @param positionId - The position ID to check
+     * @param vaultAddress - Bitcoin address of the vault
+     * @returns Array of available UTXOs
+     */
+    async getAvailableUTXOs(positionId, vaultAddress) {
+        const result = await this.calculateTrustedBalance(positionId, vaultAddress);
+        return result.availableUTXOs;
+    }
+    /**
+     * Check if a specific UTXO is available for authorization
+     *
+     * @param positionId - The position ID to check
+     * @param vaultAddress - Bitcoin address of the vault
+     * @param txid - Transaction ID of the UTXO
+     * @param vout - Output index of the UTXO
+     * @returns True if UTXO is available, false otherwise
+     */
+    async isUTXOAvailable(positionId, vaultAddress, txid, vout) {
+        const availableUTXOs = await this.getAvailableUTXOs(positionId, vaultAddress);
+        return availableUTXOs.some((utxo) => utxo.txid === txid && utxo.vout === vout);
+    }
+    /**
+     * Check if a UTXO is authorized (appears in authorized spends)
+     *
+     * @param utxo - The UTXO to check
+     * @param authorizedSpends - List of authorized spends from contract
+     * @returns True if UTXO is authorized, false otherwise
+     */
+    isUTXOAuthorized(utxo, authorizedSpends) {
+        return authorizedSpends.some((spend) => spend.txid === utxo.txid && spend.vout === utxo.vout);
+    }
+    /**
+     * Query smart contract for authorized spends
+     *
+     * Calls the contract's getAuthorizedSpends(positionId) view function
+     * to retrieve all authorized Bitcoin spends for this position.
+     *
+     * Contract struct AuthorizedSpend:
+     * - txid: string
+     * - vout: uint32
+     * - satoshis: uint256
+     * - authorizedAt: uint256 (timestamp)
+     *
+     * @param positionId - The position ID to query
+     * @returns Array of authorized spends for this position
+     */
+    async getAuthorizedSpendsFromContract(positionId) {
+        // For LIT Actions, Lit.Actions.call provides RPC access
+        // This uses the ethers.js-like interface available in LIT runtime
+        // Convert positionId to bytes32 if it's a hex string
+        const positionIdBytes32 = positionId.startsWith("0x")
+            ? positionId
+            : `0x${positionId.padStart(64, "0")}`;
+        // ABI fragment for getAuthorizedSpends function
+        const getAuthorizedSpendsABI = [
+            {
+                inputs: [
+                    { internalType: "bytes32", name: "positionId", type: "bytes32" },
+                ],
+                name: "getAuthorizedSpends",
+                outputs: [
+                    {
+                        components: [
+                            { internalType: "string", name: "txid", type: "string" },
+                            { internalType: "uint32", name: "vout", type: "uint32" },
+                            { internalType: "uint256", name: "satoshis", type: "uint256" },
+                            {
+                                internalType: "string",
+                                name: "targetAddress",
+                                type: "string",
+                            },
+                            {
+                                internalType: "uint256",
+                                name: "targetAmount",
+                                type: "uint256",
+                            },
+                            {
+                                internalType: "string",
+                                name: "changeAddress",
+                                type: "string",
+                            },
+                            {
+                                internalType: "uint256",
+                                name: "authorizedAt",
+                                type: "uint256",
+                            },
+                        ],
+                        internalType: "struct LoanOperationsManager.AuthorizedSpend[]",
+                        name: "",
+                        type: "tuple[]",
+                    },
+                ],
+                stateMutability: "view",
+                type: "function",
+            },
+        ];
+        // Get RPC URL - either from config (for local testing) or from Lit runtime
+        let rpcUrl;
+        if (this.config.rpcUrl) {
+            // Local testing: use provided RPC URL
+            rpcUrl = this.config.rpcUrl;
+        }
+        else {
+            // Production: get RPC from Lit runtime
+            // @ts-ignore - Lit.Actions is available in LIT runtime
+            rpcUrl = await Lit.Actions.getRpcUrl({ chain: this.config.chain });
+        }
+        // Use ethers.js to query the contract directly
+        // @ts-ignore - ethers is available in LIT runtime
+        // StaticJsonRpcProvider with explicit network bypasses auto-detection (required for ngrok URLs)
+        const provider = new ethers.providers.StaticJsonRpcProvider(rpcUrl, {
+            name: "any",
+            chainId: 1337,
+        });
+        // @ts-ignore - ethers is available in LIT runtime
+        const contract = new ethers.Contract(this.config.contractAddress, getAuthorizedSpendsABI, provider);
+        const result = await contract.getAuthorizedSpends(positionIdBytes32);
+        // Transform contract response to our interface
+        return result.map((spend) => ({
+            txid: spend.txid,
+            vout: Number(spend.vout),
+            satoshis: BigInt(spend.satoshis.toString()),
+            positionId: positionId,
+            targetAddress: spend.targetAddress,
+            targetAmount: BigInt(spend.targetAmount.toString()),
+            changeAddress: spend.changeAddress,
+            timestamp: Number(spend.authorizedAt),
+        }));
+    }
+}
+exports.VaultBalanceModule = VaultBalanceModule;
+/**
+ * Factory function to create VaultBalanceModule instance
+ *
+ * @param config - Configuration for the module
+ * @returns VaultBalanceModule instance
+ */
+function createVaultBalanceModule(config) {
+    return new VaultBalanceModule(config);
+}
+/**
+ * USAGE EXAMPLE:
+ *
+ * ```typescript
+ * import { createVaultBalanceModule } from './vault-balance.module';
+ * import { BitcoinDataProvider } from './bitcoin-data-provider.module';
+ *
+ * const bitcoinProvider = new BitcoinDataProvider({
+ *   providerUrl: 'https://blockstream.info/testnet/api'
+ * });
+ *
+ * const vaultBalance = createVaultBalanceModule({
+ *   contractAddress: '0x...',
+ *   chain: 'sepolia',
+ *   bitcoinProvider,
+ *   minConfirmations: 6
+ * });
+ *
+ * // Get complete balance breakdown
+ * const result = await vaultBalance.calculateTrustedBalance(
+ *   'position123',
+ *   'tb1q...'
+ * );
+ *
+ * console.log('Total Balance:', result.totalBalance, 'sats');
+ * console.log('Authorized Balance:', result.authorizedBalance, 'sats');
+ * console.log('Available Balance:', result.availableBalance, 'sats');
+ *
+ * // Or just get the available amount
+ * const available = await vaultBalance.getTrustedBalance('position123', 'tb1q...');
+ * console.log('Can authorize:', available, 'sats');
+ * ```
+ */
+//# sourceMappingURL=vault-balance.module.js.map

package/pkg-dist/src/modules/vault-balance.module.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vault-balance.module.js","sourceRoot":"","sources":["../../../src/modules/vault-balance.module.ts"],"names":[],"mappings":"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"}

package/pkg-dist/src/modules/vault-snapshot.d.ts

@@ -0,0 +1,168 @@
+/**
+ * Vault Snapshot Module - The Brain
+ *
+ * This module calculates ALL vault intelligence from simple contract state.
+ * It is the single source of truth for vault health metrics.
+ *
+ * Architecture:
+ * - Smart Contract: Stores simple state (ucdDebt, termStartTimestamp, btcCollateralSats)
+ * - This Module: Calculates everything else (ratios, thresholds, risk metrics)
+ *
+ * The vault-snapshot is used by:
+ * - Minting authorization (check if sufficient collateral)
+ * - Liquidation detection (check if under threshold)
+ * - UI display (show vault health to user)
+ * - Repayment calculations (how much can be repaid)
+ */
+import { VaultSnapshot, VaultSnapshotConfig } from "../interfaces/chunks/vault-snapshot.i";
+/**
+ * Vault Snapshot Module
+ *
+ * The intelligence layer that transforms simple contract state into
+ * comprehensive vault health metrics.
+ */
+export declare class VaultSnapshotModule {
+    private config;
+    constructor(config: VaultSnapshotConfig);
+    /**
+     * Get complete vault snapshot
+     *
+     * This is the main entry point. Returns everything you need to know
+     * about a vault's health in a single call.
+     *
+     * @param positionId - Position to snapshot
+     * @returns Complete VaultSnapshot with all metrics
+     */
+    getVaultSnapshot(positionId: string): Promise<VaultSnapshot>;
+    /**
+     * Query position state from smart contract
+     *
+     * Gets the simple state that contract stores:
+     * - positionId, pkpId, borrower, vaultAddress
+     * - ucdDebt
+     * - termStartTimestamp
+     * - selectedTerm
+     * - status
+     */
+    protected queryPositionState(positionId: string): Promise<{
+        positionId: string;
+        pkpId: string;
+        borrower: string;
+        vaultAddress: string;
+        ucdDebt: bigint;
+        termStartTimestamp: number;
+        selectedTerm: number;
+        status: number;
+    }>;
+    /**
+     * Parse vault address based on format and network
+     *
+     * Supports two formats:
+     * 1. Single string: "mqM3ZR2N6DzZkafSdFqxEAkWovAU3uYTAN"
+     * 2. JSON object: {"mainnet":"bc1q...","testnet":"mqM3ZR2N6DzZkafSdFqxEAkWovAU3uYTAN"}
+     *
+     * @param rawVaultAddress Raw vault address from contract
+     * @param chain EVM chain (sepolia, ethereum)
+     * @returns Parsed Bitcoin address for the appropriate network
+     */
+    private parseVaultAddress;
+    /**
+     * Quick check if position is liquidatable
+     *
+     * Convenience method when you only need to know if position can be liquidated.
+     *
+     * @param positionId - Position to check
+     * @returns True if position is liquidatable
+     */
+    isLiquidatable(positionId: string): Promise<boolean>;
+    /**
+     * Get collateral ratio for position
+     *
+     * Convenience method when you only need the collateral ratio.
+     *
+     * @param positionId - Position to check
+     * @returns Collateral ratio in basis points
+     */
+    getCollateralRatio(positionId: string): Promise<number>;
+    /**
+     * Get available BTC balance
+     *
+     * Convenience method when you only need available balance.
+     *
+     * @param positionId - Position to check
+     * @returns Available BTC in satoshis
+     */
+    getAvailableBalance(positionId: string): Promise<bigint>;
+    /**
+     * Check if position has sufficient collateral for new debt
+     *
+     * Used by minting authorization to validate new mints.
+     *
+     * @param positionId - Position to check
+     * @param additionalDebt - Additional UCD debt to add
+     * @param requiredRatioBps - Required collateral ratio (e.g., 13000 for 130%)
+     * @returns True if sufficient collateral exists
+     */
+    hasSufficientCollateral(positionId: string, additionalDebt: bigint, requiredRatioBps: number): Promise<boolean>;
+}
+/**
+ * Factory function to create VaultSnapshotModule
+ *
+ * @param config - Configuration
+ * @returns VaultSnapshotModule instance
+ */
+export declare function createVaultSnapshotModule(config: VaultSnapshotConfig): VaultSnapshotModule;
+/**
+ * USAGE EXAMPLE:
+ *
+ * ```typescript
+ * import { createVaultSnapshotModule } from './modules/vault-snapshot';
+ * import { BitcoinDataProvider } from './modules/bitcoin-data-provider.module';
+ * import { PriceOracleModule } from './modules/price-oracle.module';
+ *
+ * // Initialize dependencies
+ * const bitcoinProvider = new BitcoinDataProvider({
+ *   providerUrl: 'https://blockstream.info/testnet/api'
+ * });
+ *
+ * const priceOracle = new PriceOracleModule('mainnet');
+ *
+ * // Create vault balance module
+ * const vaultBalance = createVaultBalanceModule({
+ *   contractAddress: '0x...',
+ *   chain: 'sepolia',
+ *   bitcoinProvider,
+ *   minConfirmations: 6
+ * });
+ *
+ * // Create vault snapshot module
+ * const vaultSnapshot = createVaultSnapshotModule({
+ *   contractAddress: '0x...',
+ *   chain: 'sepolia',
+ *   vaultBalance,
+ *   priceOracle,
+ * });
+ *
+ * // Get complete snapshot
+ * const snapshot = await vaultSnapshot.getVaultSnapshot('position123');
+ *
+ * console.log('Position:', snapshot.positionId);
+ * console.log('Collateral Ratio:', snapshot.collateralRatioBps / 100, '%');
+ * console.log('Liquidatable:', snapshot.isLiquidatable);
+ * console.log('Days Until Expiry:', snapshot.daysUntilExpiry);
+ * console.log('Available BTC:', snapshot.availableBTCSats, 'sats');
+ *
+ * // Or use convenience methods
+ * const isLiquidatable = await vaultSnapshot.isLiquidatable('position123');
+ * const collateralRatio = await vaultSnapshot.getCollateralRatio('position123');
+ * const availableBalance = await vaultSnapshot.getAvailableBalance('position123');
+ *
+ * // Check if can mint more UCD
+ * const canMint = await vaultSnapshot.hasSufficientCollateral(
+ *   'position123',
+ *   BigInt(5000), // Want to mint 5000 more UCD
+ *   13000 // Required 130% ratio
+ * );
+ * ```
+ */
+//# sourceMappingURL=vault-snapshot.d.ts.map

package/pkg-dist/src/modules/vault-snapshot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vault-snapshot.d.ts","sourceRoot":"","sources":["../../../src/modules/vault-snapshot.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAIH,OAAO,EACL,aAAa,EACb,mBAAmB,EACpB,MAAM,uCAAuC,CAAC;AAgB/C;;;;;GAKG;AACH,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,MAAM,CAAsB;gBAExB,MAAM,EAAE,mBAAmB;IAIvC;;;;;;;;OAQG;IACG,gBAAgB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC;IA0GlE;;;;;;;;;OASG;cACa,kBAAkB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC;QAC9D,UAAU,EAAE,MAAM,CAAC;QACnB,KAAK,EAAE,MAAM,CAAC;QACd,QAAQ,EAAE,MAAM,CAAC;QACjB,YAAY,EAAE,MAAM,CAAC;QACrB,OAAO,EAAE,MAAM,CAAC;QAChB,kBAAkB,EAAE,MAAM,CAAC;QAC3B,YAAY,EAAE,MAAM,CAAC;QACrB,MAAM,EAAE,MAAM,CAAC;KAChB,CAAC;IAmHF;;;;;;;;;;OAUG;IACH,OAAO,CAAC,iBAAiB;IA8BzB;;;;;;;OAOG;IACG,cAAc,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAK1D;;;;;;;OAOG;IACG,kBAAkB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAK7D;;;;;;;OAOG;IACG,mBAAmB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAK9D;;;;;;;;;OASG;IACG,uBAAuB,CAC3B,UAAU,EAAE,MAAM,EAClB,cAAc,EAAE,MAAM,EACtB,gBAAgB,EAAE,MAAM,GACvB,OAAO,CAAC,OAAO,CAAC;CAWpB;AAED;;;;;GAKG;AACH,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,mBAAmB,GAC1B,mBAAmB,CAErB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoDG"}