@gvnrdao/dh-sdk 0.0.172 → 0.0.206

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Diamond Hands Protocol
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -12,6 +12,23 @@ The official TypeScript SDK for the Diamond Hands Protocol, enabling developers
 npm install @gvnrdao/dh-sdk
 ```
 
+### Browser vs server (PKP mint / `PKP_MINT_PRIVATE_KEY`)
+
+- **Default export** (`import { DiamondHandsSDK } from "@gvnrdao/dh-sdk"` and `import { loadSDKConfig } from "@gvnrdao/dh-sdk"` via constants) resolves **browser-safe** environment helpers (`environment.browser`) — suitable for frontends, read-only flows, and user-signed transactions. Do **not** put `PKP_MINT_PRIVATE_KEY` in client bundles.
+- **Server / Node scripts** (lit-ops-server, CI, PKP mint wallets) should import Node env + optional mint key from the dedicated subpath:
+
+```typescript
+import {
+  loadSDKConfig,
+  validateSDKEnvironment,
+} from "@gvnrdao/dh-sdk/server";
+
+validateSDKEnvironment({ requiresPrivateKey: true });
+const cfg = loadSDKConfig(); // may include cfg.pkpMintPrivateKey when env is set
+```
+
+See [`docs/security/SECRETS-POLICY.md`](../docs/security/SECRETS-POLICY.md). The repo enforces that only `src/server.ts` may import Node `environment.ts` (ESLint + `npm run lint:server-boundary`).
+
 ## Usage
 
 ### Basic Setup
@@ -19,8 +36,7 @@ npm install @gvnrdao/dh-sdk
 ```typescript
 import { DiamondHandsSDK } from "@gvnrdao/dh-sdk";
 
-// Initialize SDK
-const sdk = new DiamondHandsSDK({
+const sdkResult = await DiamondHandsSDK.create({
   mode: "service", // or 'standalone'
   serviceEndpoint: "http://localhost:3001",
   contractAddresses: {
@@ -29,8 +45,10 @@ const sdk = new DiamondHandsSDK({
     // ... other contract addresses
   },
 });
-
-await sdk.initialize();
+if (!sdkResult.success) {
+  throw sdkResult.error;
+}
+const sdk = sdkResult.value;
 ```
 
 ### Creating a Loan
@@ -50,6 +68,55 @@ if (result.success) {
 }
 ```
 
+### UCD mint gas (`requestMintUCD`)
+
+`mintUCD` can consume very high gas. The SDK runs **`eth_estimateGas`** on the final calldata, adds **25% headroom**, and caps the limit at **10M**. Fees use **`getFeeData()`** when available, with fallbacks. Broadcasting uses **`signer.sendTransaction`** (EIP-1559 type 2), not manual `signDigest` / raw RPC.
+
+If **estimateGas** fails but a **static call** succeeds, on **Sepolia (chain ID 11155111)** the SDK **automatically** sends with the **fixed ceiling**; on other chains it throws unless estimation succeeds.
+
+### Smart wallets and same-block limits (`PositionManager`)
+
+The on-chain `PositionManager` applies a **flash-loan protection** modifier to **`createPosition`** and **`extendPosition`**: it rate-limits by **`tx.origin`** (the top-level EOA or account that sent the outer transaction), not by `msg.sender`. This is intentional (anti-abuse); it is **not** used for access control.
+
+**Implications for integrators:**
+
+- **Contract wallets (e.g. Safe)** can create and extend positions: the protocol sees `msg.sender` as the wallet. Ensure you do **not** put **two** guarded calls (`create` **or** `extend`) in **one** outer transaction (e.g. a Safe multicall batch), or the second can revert with `SameBlockInteraction`.
+- At most **one successful** `createPosition` **or** `extendPosition` per **block** per **`tx.origin`**. Split operations across separate transactions/blocks if needed.
+- Flows where **many users** share the **same** outer submitter in the **same block** (e.g. some **account-abstraction / bundler** setups) can **collide** on that limit because they share `tx.origin`. EOA-submitted Safe transactions are typically unaffected.
+
+### Liquidating Positions (MEV-Protected)
+
+The SDK provides MEV-protected liquidation using a commit-reveal system:
+
+```typescript
+// MEV-protected liquidation (recommended)
+const liquidationResult = await sdk.liquidatePosition({
+  positionId: "0x...",
+  forceContractCall: false, // Use LIT action validation
+});
+
+// Legacy admin-only liquidation (faster, for testing)
+const adminResult = await sdk.liquidatePositionAdmin({
+  positionId: "0x...",
+  forceContractCall: true, // Bypass LIT action
+});
+```
+
+#### MEV Protection Features
+
+- **Commit-Reveal System**: Prevents front-running by separating intent from execution
+- **Randomized Delays**: 60-300 second delays to avoid predictable timing attacks
+- **Quantum Timestamps**: LIT Protocol signed timestamps prevent replay attacks
+- **Role-Based Access**: Uses LIQUIDATOR_ROLE instead of admin privileges
+
+#### Liquidation Process
+
+1. **Commit Phase**: Submit liquidation intent with LIT Action validation
+2. **MEV Protection**: Wait randomized delay (60-300 seconds)
+3. **Reveal Phase**: Execute liquidation with deadline enforcement
+
+**Note**: The commit-reveal process takes 1-5 minutes due to MEV protection. Use `liquidatePositionAdmin()` for immediate execution during testing or emergency situations.
+
 ## Features
 
 - ✅ **Service & Standalone Modes**: Flexible deployment options
@@ -58,6 +125,7 @@ if (result.success) {
 - ✅ **PKP Integration**: Secure key management with LIT Protocol
 - ✅ **Smart Contract Integration**: Direct interaction with Diamond Hands contracts
 - ✅ **Bitcoin Operations**: Support for Bitcoin deposit verification
+- ✅ **MEV-Protected Liquidations**: Commit-reveal system prevents front-running
 - ✅ **Telegram Notifications**: Optional event notifications (Node.js only)
 
 ## API Reference
@@ -67,11 +135,13 @@ if (result.success) {
 - `initialize()` - Initialize the SDK
 - `createLoan(request)` - Create a new loan position
 - `repayLoan(positionId, amount)` - Repay an existing loan
-- `liquidatePosition(positionId)` - Liquidate an undercollateralized position
+- `liquidatePosition(request)` - Liquidate an undercollateralized position (MEV-protected)
+- `liquidatePositionAdmin(request)` - Liquidate position using admin-only access (backward compatibility)
 
 ### Configuration Options
 
 See the full API documentation for detailed configuration options and method signatures.
+- API Reference (TSDoc source): [`src/index.ts`](src/index.ts)
 
 ## Telegram Notifications
 
@@ -109,6 +179,7 @@ The SDK sends notifications for:
 - UCD minting
 - Partial payments
 - Loan renewals
+- Position liquidations
 - Balance confirmations
 - BTC withdrawals
 - Operation failures
@@ -117,6 +188,16 @@ The SDK sends notifications for:
 
 Never expose your Telegram bot token in frontend code. If you need notifications from browser applications, use a backend webhook endpoint instead.
 
+## Development — TypeChain
+
+After changing Solidity contracts that the SDK consumes:
+
+1. `cd contracts && npm run compile` (or from `sdk/`: `npm run sync:typechain`).
+2. Commit updated `contracts/typechain-types/**` with the contract changes.
+3. Update [`sdk/src/contracts/typechain-contracts.ts`](src/contracts/typechain-contracts.ts) re-exports if new contracts need SDK-facing types.
+
+Full details: [`docs/TYPECHAIN_IMPLEMENTATION.md`](docs/TYPECHAIN_IMPLEMENTATION.md) (regeneration, commit policy, npm publish behavior).
+
 ## License
 
 MIT

package/browser/dist/index.d.ts

@@ -1,9 +1,8 @@
-import * as SDKModule from "../dist/index.js";
-export declare const DiamondHandsSDK: typeof SDKModule.DiamondHandsSDK;
+export declare const DiamondHandsSDK: any;
 export type CreateLoanRequest = any;
 export type CreateLoanResult = any;
 export type DiamondHandsSDKConfig = any;
-export * from "../dist/index.js";
-declare const _default: typeof SDKModule.DiamondHandsSDK;
+export declare const AuthParamsValidation: any, BPSConversions: any, BitcoinOperations: any, CacheManager: any, ContractManager: any, SDKClass: any, ErrorCategory: any, ErrorSeverity: any, EventHelpers: any, LoanCreator: any, LoanQuery: any, LoanStatus: any, PaymentType: any, PositionStatus: any, SDKError: any, SatoshisConversions: any, UCDConversions: any, WeiConversions: any, createBitcoinOperations: any, createCacheManager: any, createContractManager: any, createLoanCreator: any, createLoanQuery: any, createPKPManager: any, failure: any, success: any, tryCatch: any, tryCatchAsync: any, unwrap: any, unwrapOr: any, validateSDKConfig: any;
+declare const _default: any;
 export default _default;
 //# sourceMappingURL=index.d.ts.map

package/browser/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,SAAS,MAAM,kBAAkB,CAAC;AAY9C,eAAO,MAAM,eAAe,kCAA4B,CAAC;AAoCzD,MAAM,MAAM,iBAAiB,GAAG,GAAG,CAAC;AACpC,MAAM,MAAM,gBAAgB,GAAG,GAAG,CAAC;AACnC,MAAM,MAAM,qBAAqB,GAAG,GAAG,CAAC;AAOxC,cAAc,kBAAkB,CAAC;;AAOjC,wBAAyC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAiBA,eAAO,MAAM,eAAe,KAA4B,CAAC;AAgCzD,MAAM,MAAM,iBAAiB,GAAG,GAAG,CAAC;AACpC,MAAM,MAAM,gBAAgB,GAAG,GAAG,CAAC;AACnC,MAAM,MAAM,qBAAqB,GAAG,GAAG,CAAC;AAQxC,eAAO,MACL,oBAAoB,OACpB,cAAc,OACd,iBAAiB,OACjB,YAAY,OACZ,eAAe,OACE,QAAQ,OACzB,aAAa,OACb,aAAa,OACb,YAAY,OACZ,WAAW,OACX,SAAS,OACT,UAAU,OACV,WAAW,OACX,cAAc,OACd,QAAQ,OACR,mBAAmB,OACnB,cAAc,OACd,cAAc,OACd,uBAAuB,OACvB,kBAAkB,OAClB,qBAAqB,OACrB,iBAAiB,OACjB,eAAe,OACf,gBAAgB,OAChB,OAAO,OACP,OAAO,OACP,QAAQ,OACR,aAAa,OACb,MAAM,OACN,QAAQ,OACR,iBAAiB,KACN,CAAC;;AAOd,wBAAyC"}

package/browser/dist/index.js

@@ -1,8 +1,8 @@
 // Browser ESM entry point for Diamond Hands SDK
 // Converts CommonJS exports to ES module imports for browser compatibility
 // Uses the proven wrapper pattern from test-app/src/lib/lit-ops-wrapper.ts
-// Import from the original built SDK
-import * as SDKModule from "../dist/index.js";
+// Import from the original built SDK (CommonJS module)
+const SDKModule = require("../dist/index.js");
 // Import lit-ops and lit-actions (using the wrapper pattern)
 // TODO: Re-enable when these modules have proper ES module builds
 // import * as LitOpsModule from "../../lit-ops/dist/index.js";
@@ -16,7 +16,8 @@ export const DiamondHandsSDK = SDKModule.DiamondHandsSDK;
 // RE-EXPORT CORE SDK ONLY
 // ========================================
 // Re-export core SDK exports only to avoid conflicts
-export * from "../dist/index.js";
+// Note: CommonJS module, so we export specific items
+export const { AuthParamsValidation, BPSConversions, BitcoinOperations, CacheManager, ContractManager, DiamondHandsSDK: SDKClass, ErrorCategory, ErrorSeverity, EventHelpers, LoanCreator, LoanQuery, LoanStatus, PaymentType, PositionStatus, SDKError, SatoshisConversions, UCDConversions, WeiConversions, createBitcoinOperations, createCacheManager, createContractManager, createLoanCreator, createLoanQuery, createPKPManager, failure, success, tryCatch, tryCatchAsync, unwrap, unwrapOr, validateSDKConfig, } = SDKModule;
 // ========================================
 // DEFAULT EXPORT
 // ========================================

package/dist/constants/chunks/contract-abis.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Smart Contract ABIs
+ */
+export declare const POSITION_MANAGER_ABI: readonly ["function createPosition(bytes32 pkpId, bytes calldata validatorSignature, address borrower, string calldata vaultAddress, uint256 selectedTermMonths) external returns (bool)", "function getPositionById(bytes32 positionId) external view returns (tuple(bytes32 positionId, bytes32 pkpId, uint256 ucdDebt, string vaultAddress, address borrower, uint40 createdAt, uint40 lastUpdated, uint16 selectedTerm, uint40 expiryAt, uint8 status))", "function getUserPositions(address user) external view returns (bytes32[] memory)", "function calculateCollateralRatio(bytes32 positionId) external view returns (uint256)", "function hasRole(bytes32 role, address account) external view returns (bool)", "function ADMIN_ROLE() external view returns (bytes32)", "function paused() external view returns (bool)", "function mintUCD(bytes32 positionId, uint256 mintAmount, uint256 mintFee, uint256 newDebt, uint256 newCollateral, uint256 btcPrice, bytes32 authorizedSpendsHash, bytes32 ucdDebtHash, bytes32 contractHash, uint256 quantumTimestamp, bytes calldata mintValidatorSignature) external returns (bool)", "function repayPosition(bytes32 positionId, uint256 repaymentAmount) external returns (bool)", "function makePayment(bytes32 positionId, uint256 paymentAmount, uint256 quantumTimestamp, uint256 btcPrice, bytes calldata paymentValidatorSignature) external returns (bool)", "function withdrawBTC(bytes32 positionId, string withdrawalAddress, uint256 networkFee) external returns (bool)", "function extendPosition(bytes32 positionId, uint256 selectedTerm, uint256 quantumTimestamp, uint256 btcPrice, uint256 availableBTCBalance, bytes calldata extensionValidatorSignature) external returns (bool)", "function liquidatePosition(bytes32 positionId) external returns (bool)", "function commitLiquidation(bytes32 positionId, bytes32 commitHash) external", "function revealAndLiquidate(bytes32 positionId, uint256 nonce, uint256 deadline) external returns (bool)", "function getExpiredLoanLiquidationThreshold(bytes32 positionId) external view returns (uint256)", "function isExpiredLoanLiquidatable(bytes32 positionId, uint256 collateralValue, uint256 debtAmount) external view returns (bool)", "event PositionCreated(bytes32 indexed positionId, bytes32 indexed pkpId, address indexed borrower, uint256 requestedCollateralRatio, uint256 selectedTerm, uint256 expiryAt)", "event UCDMinted(bytes32 indexed positionId, uint256 amount, bytes proof)", "event PositionLiquidated(bytes32 indexed positionId, address indexed liquidator, uint256 collateralRatio, uint256 debtRepaid, uint256 collateralValue, bool wasExpired, uint256 timestamp)", "event CollateralRatioUpdated(bytes32 indexed positionId, uint256 oldRatio, uint256 newRatio)", "event PositionUpdated(bytes32 indexed positionId, uint256 oldDebt, uint256 newDebt)"];
+export declare const UCD_TOKEN_ABI: readonly ["function balanceOf(address account) external view returns (uint256)", "function transfer(address to, uint256 amount) external returns (bool)", "function approve(address spender, uint256 amount) external returns (bool)", "function allowance(address owner, address spender) external view returns (uint256)", "function mint(address to, uint256 amount) external", "function burn(uint256 amount) external", "function burnFrom(address account, uint256 amount) external", "event Transfer(address indexed from, address indexed to, uint256 value)", "event Approval(address indexed owner, address indexed spender, uint256 value)"];
+export declare const PRICE_FEED_CONSUMER_ABI: readonly ["function getCurrentPrice() external view returns (uint256)", "function isPriceStale() external view returns (bool)", "function updatePrice() external", "event PriceUpdated(uint256 indexed price, uint256 timestamp)"];
+export declare const PSM_ABI: readonly ["function swap(address stablecoin, uint256 amountIn, uint256 minUcdOut) external returns (uint256 ucdAmount)", "function addSupportedStablecoin(address stablecoin, uint256 exchangeRate, uint256 entryFeeBps, uint256 exitFeeBps, uint8 decimals, uint256 minSwapAmount, uint256 minRedeemAmount) external", "function updateSupportedStablecoin(address stablecoin, uint256 exchangeRate, uint256 entryFeeBps, uint256 exitFeeBps, uint8 decimals, uint256 minSwapAmount, uint256 minRedeemAmount) external", "function removeSupportedStablecoin(address stablecoin) external", "function withdrawStablecoin(address stablecoin, uint256 amount) external", "function pause() external", "function unpause() external", "function redeem(address stablecoin, uint256 ucdAmount, uint256 minStablecoinOut) external returns (uint256 stablecoinAmount)", "function setExitFee(address stablecoin, uint256 fee) external", "function setEntryFee(address stablecoin, uint256 fee) external", "function setExchangeRate(address stablecoin, uint256 rate) external", "function setRedeemEnabled(bool enabled) external", "function addReserves(address stablecoin, uint256 amount) external", "function syncReserves(address stablecoin) external", "function forceSyncReserves(address stablecoin) external", "function getRedemptionQuote(address stablecoin, uint256 ucdAmount) external view returns (uint256 stablecoinOut, uint256 exitFee)", "function getAvailableReserves(address stablecoin) external view returns (uint256)", "function canRedeem(address stablecoin, uint256 ucdAmount) external view returns (bool)", "function version() external pure returns (string memory)", "function supportedStablecoins(address) external view returns (bool)", "function exchangeRates(address) external view returns (uint256)", "function fees(address) external view returns (uint256)", "function exitFees(address) external view returns (uint256)", "function reserves(address) external view returns (uint256)", "function redeemEnabled() external view returns (bool)", "function stablecoinDecimals(address) external view returns (uint8)", "function lastOperationBlock(address) external view returns (uint256)", "function operationCount(address) external view returns (uint256)", "function BASIS_POINTS() external view returns (uint256)", "function EXCHANGE_RATE_SCALE() external view returns (uint256)", "function MAX_EXIT_FEE() external view returns (uint256)", "function MAX_RESERVE_DRIFT() external view returns (uint256)", "event Swap(address indexed user, address indexed stablecoin, uint256 stablecoinAmount, uint256 ucdAmount, uint256 fee, uint256 timestamp)", "event Redeem(address indexed user, address indexed stablecoin, uint256 ucdAmount, uint256 stablecoinAmount, uint256 exitFee, uint256 timestamp)", "event StablecoinAdded(address indexed stablecoin, uint256 exchangeRate, uint256 fee)", "event StablecoinRemoved(address indexed stablecoin)", "event ReserveUpdated(address indexed stablecoin, uint256 oldReserve, uint256 newReserve)", "event ExitFeeUpdated(address indexed stablecoin, uint256 oldFee, uint256 newFee)", "event EntryFeeUpdated(address indexed stablecoin, uint256 oldFee, uint256 newFee)", "event ExchangeRateUpdated(address indexed stablecoin, uint256 oldRate, uint256 newRate)"];

package/dist/constants/chunks/deployment-addresses.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Auto-generated deployment addresses
+ * Generated by scripts/sync-deployments.js
+ * Do not edit manually - this file is overwritten during build
+ */
+export interface DeploymentLatestEnv {
+    [key: string]: string | number | undefined;
+}
+export interface DeploymentContracts {
+    PositionManagerProxy?: string;
+    PositionManager?: string;
+    PositionManagerCoreModule?: string;
+    PositionManagerViews?: string;
+    SimplePSMV2?: string;
+    LoanOperationsManagerModule?: string;
+    BTCSpendAuthorizer?: string;
+    TermManagerModule?: string;
+    CircuitBreakerModule?: string;
+    LiquidationManagerModule?: string;
+    CollateralManagerModule?: string;
+    AdminModule?: string;
+    UCDToken?: string;
+    UCDController?: string;
+    UCDMintingRewards?: string;
+    UpgradeValidator?: string;
+    BTCProofValidator?: string;
+    LITActionValidator?: string;
+    BitcoinProviderRegistry?: string;
+    PriceFeedConsumer?: string;
+    OperationAuthorizationRegistry?: string;
+    PKPValidation?: string;
+    EmergencyStorageUpdate?: string;
+    mockUsdcToken?: string;
+    mockUsdcOwner?: string;
+    mockUsdtToken?: string;
+    mockUsdtOwner?: string;
+    [key: string]: string | undefined;
+}
+export interface DeploymentData {
+    network: string;
+    chainId?: number;
+    timestamp: string;
+    deployer: string;
+    contracts: DeploymentContracts;
+    /** Flat assignments from contracts/deployments/full-{network}-latest.env (proxies, impls, validators, etc.) */
+    latestEnv?: DeploymentLatestEnv;
+    [key: string]: any;
+}
+export declare const SEPOLIA_DEPLOYMENT: DeploymentData;
+export declare const SEPOLIA_CONTRACTS: DeploymentContracts;
+export declare const LOCALHOST_DEPLOYMENT: DeploymentData;
+export declare const LOCALHOST_CONTRACTS: DeploymentContracts;
+export declare const ALL_DEPLOYMENTS: {
+    readonly sepolia: DeploymentData;
+    readonly localhost: DeploymentData;
+};
+export declare const ALL_CONTRACTS: {
+    readonly sepolia: DeploymentContracts;
+    readonly localhost: DeploymentContracts;
+};
+/**
+ * Get deployment data by network name
+ */
+export declare function getDeploymentByNetwork(network: string): DeploymentData | null;
+/**
+ * Get contract addresses by network name
+ */
+export declare function getContractsByNetwork(network: string): DeploymentContracts | null;

package/dist/constants/chunks/encrypted-provider-params.d.ts

@@ -0,0 +1,21 @@
+export type EncryptedPriceProvider = {
+    name: string;
+    pkpId: string;
+    apiKey: string;
+    apiSecret?: string;
+};
+type RegistryProvider = {
+    name: string;
+    pkpId: string;
+    apiKeyEncrypted: string;
+    apiSecretEncrypted?: string;
+    version: number;
+    updatedAt: string;
+};
+type EncryptedParamsRegistry = {
+    network: string;
+    providers: RegistryProvider[];
+};
+export declare function loadEncryptedProviderRegistry(registryPath?: string): EncryptedParamsRegistry;
+export declare function getEncryptedPriceProviders(providerNames?: string[], registryPath?: string): EncryptedPriceProvider[];
+export {};

package/dist/constants/chunks/environment.browser.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Environment Configuration for Diamond Hands SDK - Browser Version
+ * Browser-compatible environment handling without Node.js dependencies
+ */
+import { LitNetwork } from "@gvnrdao/dh-lit-ops";
+/** SDK environment label — mirrors `LIT_NETWORK` for supported networks. */
+export type EnvironmentName = "chipotle";
+export interface SDKConfig {
+    environment: EnvironmentName;
+    litNetwork: LitNetwork;
+    realLitTesting: boolean;
+    debugMode: boolean;
+    runRealIntegrationTests: boolean;
+    litRelayUrl?: string;
+    ethRpcUrl: string;
+    polygonRpcUrl: string;
+    pkpMintPrivateKey?: string;
+}
+/**
+ * Resolved Lit network from `LIT_NETWORK` / `VITE_LIT_NETWORK` (default: production **chipotle**).
+ */
+export declare function resolveLitNetworkFromEnv(): LitNetwork;
+/**
+ * SDK environment label derived from `LIT_NETWORK` (default **chipotle**).
+ */
+export declare function getCurrentEnvironment(): EnvironmentName;
+/**
+ * Load and validate SDK configuration from environment
+ */
+export declare function loadSDKConfig(): SDKConfig;
+/**
+ * Get LIT Network configuration
+ */
+export declare function getLitNetworkConfig(networkName: LitNetwork): LitNetwork;
+/**
+ * Environment-aware console logging
+ */
+export declare function envLog(message: string, ...args: any[]): void;
+/**
+ * Validate SDK environment requirements
+ */
+export declare function validateSDKEnvironment(requirements: {
+    requiresRealLitTesting?: boolean;
+    requiresPrivateKey?: boolean;
+}): SDKConfig;

package/dist/constants/chunks/environment.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Environment Configuration for Diamond Hands SDK (Node only)
+ *
+ * Loads and validates environment variables with multi-path `.env` discovery.
+ * Used for server-side flows that may read `PKP_MINT_PRIVATE_KEY`.
+ *
+ * **Do not import this file from browser-oriented modules.** Import via
+ * `@gvnrdao/dh-sdk/server` only. Shared / client code should use `environment.browser`.
+ *
+ * **Observability:** With `DEBUG_SDK=true`, logs once which `.env` paths were attempted
+ * and which existing files were merged (later overrides earlier).
+ *
+ * **Strict merge checks:** Detecting conflicting definitions of the same variable across
+ * multiple `.env` files is not implemented; reserved for a future CI-gated workflow once
+ * the repo has automated SDK checks in CI.
+ */
+import { LitNetwork } from "@gvnrdao/dh-lit-ops";
+/** SDK environment label — mirrors `LIT_NETWORK` for supported networks. */
+export type EnvironmentName = "chipotle";
+export interface SDKConfig {
+    environment: EnvironmentName;
+    litNetwork: LitNetwork;
+    realLitTesting: boolean;
+    debugMode: boolean;
+    runRealIntegrationTests: boolean;
+    litRelayUrl?: string;
+    ethRpcUrl: string;
+    polygonRpcUrl: string;
+    pkpMintPrivateKey?: string;
+}
+/**
+ * Resolved Lit network from `LIT_NETWORK` (default: production **chipotle**).
+ */
+export declare function resolveLitNetworkFromEnv(): LitNetwork;
+/**
+ * SDK environment label derived from `LIT_NETWORK` (default **chipotle**).
+ */
+export declare function getCurrentEnvironment(): EnvironmentName;
+/**
+ * Load and validate SDK configuration from environment
+ */
+export declare function loadSDKConfig(): SDKConfig;
+/**
+ * Get LIT Network configuration
+ */
+export declare function getLitNetworkConfig(networkName: LitNetwork): LitNetwork;
+/**
+ * Environment-aware console logging
+ */
+export declare function envLog(message: string, ...args: any[]): void;
+/**
+ * Validate SDK environment requirements
+ */
+export declare function validateSDKEnvironment(requirements: {
+    requiresRealLitTesting?: boolean;
+    requiresPrivateKey?: boolean;
+}): SDKConfig;

package/dist/constants/chunks/network-configs.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Network Configuration Constants
+ * Automatically loads contract addresses from deployment files
+ * Browser-friendly implementation with silent fallbacks
+ */
+/**
+ * Network Configuration Interface
+ */
+export interface NetworkConfig {
+    mode: "service" | "standalone";
+    serviceEndpoint: string;
+    chainId: number;
+    name: string;
+    rpcUrls: string[];
+    contractAddresses: {
+        positionManager: string;
+        positionManagerCore?: string;
+        positionManagerViews?: string;
+        simplePsmV2?: string;
+        loanOperationsManager?: string;
+        termManager?: string;
+        circuitBreaker?: string;
+        liquidationManager?: string;
+        ucdToken: string;
+        ucdController?: string;
+        priceFeedConsumer: string;
+        operationAuthorizationRegistry?: string;
+        btcSpendAuthorizer?: string;
+        bitcoinProviderRegistry?: string;
+        mockUsdcToken?: string;
+        mockUsdtToken?: string;
+        mockUsdcOwner?: string;
+    };
+    subgraphs: {
+        diamondHandsUrl?: string;
+        tokenGvnrUrl?: string;
+    };
+    litNetwork: string;
+    validatorVersion?: number;
+    debug: boolean;
+}
+/**
+ * Network Configuration Registry
+ */
+export declare const NETWORK_CONFIGS: Record<number, NetworkConfig>;
+/**
+ * Get network configuration by chain ID
+ */
+export declare function getNetworkConfig(chainId: number): NetworkConfig | null;
+/**
+ * Get network configuration by human-readable name (e.g., "sepolia")
+ */
+export declare function getNetworkConfigByName(name: string): NetworkConfig | null;
+/**
+ * Get all supported network configurations
+ */
+export declare function getAllNetworkConfigs(): NetworkConfig[];
+/**
+ * Check if a network is supported
+ */
+export declare function isNetworkSupported(chainId: number): boolean;
+/**
+ * Default network fallbacks
+ */
+export declare const DEFAULT_NETWORK_CONFIG: Partial<NetworkConfig>;

package/dist/constants/chunks/sdk-config.d.ts

@@ -0,0 +1,33 @@
+/**
+ * SDK Configuration Constants
+ */
+import type { LitNetwork } from "@gvnrdao/dh-lit-ops";
+export declare const DEFAULT_NETWORKS: {
+    readonly ETHEREUM_MAINNET: "https://eth-mainnet.g.alchemy.com/v2/";
+    readonly ETHEREUM_SEPOLIA: "https://eth-sepolia.g.alchemy.com/v2/";
+    readonly POLYGON_MAINNET: "https://polygon-mainnet.g.alchemy.com/v2/";
+    readonly LOCAL_HARDHAT: "http://localhost:8545";
+};
+export declare const DEFAULT_LIT_NETWORKS: {
+    readonly CHIPOTLE: "chipotle";
+};
+/**
+ * Default Lit network when `LIT_NETWORK` is unset or config omits `litNetwork`.
+ */
+export declare const DEFAULT_LIT_NETWORK: "chipotle";
+/** Supported Lit Protocol networks for this SDK (Chipotle). */
+export declare const VALID_LIT_NETWORKS: readonly LitNetwork[];
+export declare const SDK_DEFAULTS: {
+    readonly SESSION_EXPIRATION_MINUTES: 60;
+    readonly TRANSACTION_TIMEOUT_MS: 30000;
+    readonly RETRY_ATTEMPTS: 3;
+    readonly DEBUG: false;
+};
+export declare const SDK_ERROR_MESSAGES: {
+    readonly NOT_INITIALIZED: "SDK not initialized. Call initialize() first.";
+    readonly INVALID_CONFIG: "Invalid SDK configuration provided.";
+    readonly NETWORK_ERROR: "Network connection error occurred.";
+    readonly TRANSACTION_FAILED: "Transaction failed to execute.";
+    readonly PKP_CREATION_FAILED: "PKP creation failed.";
+    readonly SIGNATURE_INVALID: "Invalid signature provided.";
+};

package/dist/constants/chunks/sdk-limits.d.ts

@@ -0,0 +1,66 @@
+/**
+ * SDK Limits and Configuration Constants
+ * Centralized constants for magic numbers used throughout the SDK
+ */
+/**
+ * Maximum batch size for The Graph queries
+ * The Graph has a hard limit of 1000 items per query
+ */
+export declare const THE_GRAPH_MAX_BATCH_SIZE = 1000;
+/**
+ * Maximum rows per page for pagination
+ * Prevents excessive memory usage and query timeouts
+ */
+export declare const MAX_PAGINATION_ROWS = 1000;
+/**
+ * Default rows per page for pagination
+ */
+export declare const DEFAULT_PAGINATION_ROWS = 10;
+/**
+ * Default maximum number of retries for failed operations
+ */
+export declare const DEFAULT_MAX_RETRIES = 3;
+/**
+ * Default operation timeout in milliseconds
+ */
+export declare const DEFAULT_OPERATION_TIMEOUT_MS = 30000;
+/**
+ * Default PKP address cache size
+ */
+export declare const DEFAULT_PKP_CACHE_SIZE = 500;
+/**
+ * Default PKP address cache TTL in milliseconds
+ */
+export declare const DEFAULT_PKP_CACHE_TTL_MS = 300000;
+/**
+ * Default balance cache size
+ */
+export declare const DEFAULT_BALANCE_CACHE_SIZE = 1000;
+/**
+ * Default balance cache TTL in milliseconds
+ */
+export declare const DEFAULT_BALANCE_CACHE_TTL_MS = 60000;
+/**
+ * Default cache cleanup interval in milliseconds
+ */
+export declare const DEFAULT_CACHE_CLEANUP_INTERVAL_MS = 300000;
+/**
+ * Default number of blocks for PSM rate limit reset period
+ */
+export declare const PSM_RATE_LIMIT_RESET_BLOCKS = 100;
+/**
+ * Maximum operations per PSM rate limit window
+ */
+export declare const PSM_MAX_OPERATIONS_PER_WINDOW = 10;
+/**
+ * Default maximum concurrent operations
+ */
+export declare const DEFAULT_CONCURRENCY_LIMIT = 10;
+/**
+ * Default Bitcoin provider consensus mode
+ */
+export declare const DEFAULT_BITCOIN_CONSENSUS_MODE: "majority";
+/**
+ * Minimum number of Bitcoin providers for consensus
+ */
+export declare const MIN_BITCOIN_PROVIDERS_FOR_CONSENSUS = 2;

package/dist/constants/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Diamond Hands SDK Constants
+ * All constants used in the SDK package
+ *
+ * Following the golden source pattern with organized chunks
+ *
+ * **Environment:** This barrel exports **browser-safe** `environment.browser` only.
+ * For Node-only config including `PKP_MINT_PRIVATE_KEY` / dotenv paths, use
+ * `@gvnrdao/dh-sdk/server` (see `src/server.ts`).
+ */
+export * from "./chunks/sdk-config";
+export * from "./chunks/network-configs";
+export * from "./chunks/environment.browser";
+export * from "./chunks/contract-abis";
+export * from "./chunks/sdk-limits";

package/dist/graphs/client.d.ts

@@ -0,0 +1,19 @@
+export interface GraphClientConfig {
+    endpoint: string;
+    requestTimeoutMs?: number;
+    maxRetries?: number;
+    headers?: Record<string, string>;
+}
+export declare class GraphClient {
+    private endpoint;
+    private requestTimeoutMs;
+    private maxRetries;
+    private headers?;
+    constructor(config: GraphClientConfig);
+    execute<T>(query: string, variables?: Record<string, any>): Promise<T>;
+    paginate<TItem>(query: string, variables: Record<string, any>, select: (page: any) => TItem[], options?: {
+        pageSize?: number;
+        maxPages?: number;
+    }): Promise<TItem[]>;
+    private backoff;
+}